Identity Profiles

An identity profile is a named, reusable configuration snapshot, generation defaults plus an adapter config, that you can pass to any identity endpoint via profile_id. Create it once, reference it everywhere.

Zero data retention

ImagePipeline never stores face images. A profile's storage config is a pointer to your own bucket, the API never accesses it, and your encryption key is never sent to or stored by the API.

Create a profile

Only name is required. Everything else pins a generation snapshot so every run on this identity is consistent: a prompt_template describing the person, plus defaults like steps, cfg_scale, seed_strategy / fixed_seed, height / width, and output_format. prompt_template_mode controls how the template joins the caller's prompt: suffix (default) appends the identity to your prompt, prefix prepends it, and replace ignores the caller prompt entirely.

cURL

curl -X POST https://api.imagepipeline.io/profiles/v1 \
  -H "X-API-Key: $IMAGEPIPELINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Caucasian Woman",
  "description": "Reusable casting identity",
  "prompt_template": "Caucasian woman, late 20s, fair porcelain skin, blonde hair, blue eyes, light natural makeup, warm expression",
  "prompt_template_mode": "suffix",
  "steps": 9,
  "cfg_scale": 0.0,
  "seed_strategy": "fixed",
  "fixed_seed": 42,
  "height": 1024,
  "width": 1024,
  "output_format": "png"
}'

JavaScript

const res = await fetch("https://api.imagepipeline.io/profiles/v1", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.IMAGEPIPELINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Caucasian Woman",
    description: "Reusable casting identity",
    prompt_template:
      "Caucasian woman, late 20s, fair porcelain skin, blonde hair, blue eyes, light natural makeup, warm expression",
    prompt_template_mode: "suffix",
    steps: 9,
    cfg_scale: 0.0,
    seed_strategy: "fixed",
    fixed_seed: 42,
    height: 1024,
    width: 1024,
    output_format: "png",
  }),
});
const profile = await res.json();

Python

import requests

res = requests.post(
    "https://api.imagepipeline.io/profiles/v1",
    headers={"X-API-Key": API_KEY},
    json={
        "name": "Caucasian Woman",
        "description": "Reusable casting identity",
        "prompt_template": "Caucasian woman, late 20s, fair porcelain skin, blonde hair, blue eyes, light natural makeup, warm expression",
        "prompt_template_mode": "suffix",
        "steps": 9,
        "cfg_scale": 0.0,
        "seed_strategy": "fixed",
        "fixed_seed": 42,
        "height": 1024,
        "width": 1024,
        "output_format": "png",
    },
)
profile = res.json()

Java

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.imagepipeline.io/profiles/v1"))
    .header("X-API-Key", System.getenv("IMAGEPIPELINE_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
{
  "name": "Caucasian Woman",
  "description": "Reusable casting identity",
  "prompt_template": "Caucasian woman, late 20s, fair porcelain skin, blonde hair, blue eyes, light natural makeup, warm expression",
  "prompt_template_mode": "suffix",
  "steps": 9,
  "cfg_scale": 0.0,
  "seed_strategy": "fixed",
  "fixed_seed": 42,
  "height": 1024,
  "width": 1024,
  "output_format": "png"
}
"""))
    .build();
HttpResponse<String> res = client.send(req, BodyHandlers.ofString());

The response echoes the saved snapshot under adapter_snapshot:

{
  "profile_id": "prof_6a14528a38a84afb",
  "name": "Caucasian Woman",
  "adapter_snapshot": {
    "prompt_template": "Caucasian woman, late 20s, fair porcelain skin, blonde hair, blue eyes, light natural makeup, warm expression",
    "prompt_template_mode": "suffix",
    "steps": 9,
    "cfg_scale": 0.0,
    "seed_strategy": "fixed",
    "fixed_seed": 42,
    "height": 1024,
    "width": 1024,
    "output_format": "png"
  }
}

Use a profile

Pass profile_id to any generation or identity endpoint. The profile's snapshot is applied, and its prompt_template is merged with your prompt per prompt_template_mode. Here the caller describes the scene and wardrobe; the profile supplies the identity (suffix mode), so the same fixed_seed keeps the face consistent across every shot:

{
  "prompt": "Beautiful woman in a dynamic pose, minimal dewy makeup, clean brows, pink crop top, pink boot-cut sequin pants, direct gaze, white background, studio lighting, photorealistic",
  "profile_id": "prof_6a14528a38a84afb"
}

Build a reusable casting library

Create a profile per identity once, then run the same scene prompt across all of them to localise a campaign or cast a diverse set, no reshoot, consistent every time:

# Each profile is a saved identity (e.g. "Caucasian Woman", "South Asian Woman",
# "East Asian Woman", "African Woman", "Latin Woman").
scene = "Beautiful woman in a dynamic pose, pink crop top, pink sequin pants, white background, studio lighting, photorealistic"

for profile_id in roster:  # the profile_ids you created above
    res = requests.post(
        "https://api.imagepipeline.io/generate/image/v1",
        headers={"X-API-Key": API_KEY},
        json={"prompt": scene, "profile_id": profile_id},
    )
    job_id = res.json()["job_id"]
    # poll GET /generate/image/v1/status/{job_id} until completed

Manage profiles

Operation	Endpoint
Create	POST /profiles/v1
List	GET /profiles/v1
Get	GET /profiles/v1/{profile_id}
Update	PATCH /profiles/v1/{profile_id}
Delete	DELETE /profiles/v1/{profile_id}

See the API Reference for the full IdentityProfileCreate schema.