Create a Character

Endpoint

POST /v1/character

Returns 202 Accepted immediately. Downloading your reference images and starting the sheet happens in the background, so all reference failures surface on the character resource, not on this response.

Request body

{
  "image_urls": [
    "https://example.com/photos/01.jpg",
    "https://example.com/photos/02.jpg",
    "https://example.com/photos/03.jpg"
  ],
  "name": "Ava — spring campaign",
  "include_outfits": false
}

Field	Type	Required	Description
`image_urls`	`string[]`	Yes	1–20 hosted `http(s)` URLs or `data:` URIs. All must show the same person. Internal/private addresses are rejected.
`name`	`string`	No	Max 120 chars. A label for your own use — echoed back on reads and never enters a prompt.
`include_outfits`	`boolean`	No	Default `false`. `true` fans the finished sheet out into five outfit variants: six images and 6× the cost instead of one. Fixed at create — regenerate reuses it, and it cannot be changed afterwards.

Response — `202 Accepted`

{
  "id": "9f1c8400-e29b-41d4-a716-446655440021",
  "status": "pending",
  "model": "dola-seedream-5-0-pro-260628",
  "estimated_cost": 6,
  "image_count": 1,
  "include_outfits": false,
  "poll_url": "/public/v1/character/9f1c8400-e29b-41d4-a716-446655440021"
}

Poll the character with GET /character/{id}.

How many photos to send

More is not automatically better.

Count	Outcome
1–2	Works, but returns a `few_references` warning. The model has too little to triangulate a consistent face from and tends to invent detail.
4–8	The sweet spot. Varied angles and lighting, same person, same approximate hairstyle.
up to 20	Accepted and stored, but only the first 10 reach the model — see below.

The 20 / 10 rule

You may submit 20 references. The model accepts 10.

We store all 20 and send the first 10 by submission order. The extras cost you nothing, and they become useful the moment the model's cap rises or the selection is retuned — whereas discarding them at the door would be irreversible.

The character resource reports all three numbers, because they answer three different questions:

"references": {
  "provided": 20,
  "stored": 18,
  "sent_to_model": 10,
  "failed": [
    {
      "index": 6,
      "source_url": "https://example.com/photos/07.jpg",
      "error": "download failed: status 404"
    }
  ]
}

provided > stored produces a references_partially_failed warning — but the run still proceeds on whatever survived. Only if zero references download does the character fail outright.

If your balance runs out part-way through the outfit fan-out, the sheet and any outfits already dispatched still complete; the remaining outfits are skipped and the character reports an outfit_dispatch_failed warning with the reason insufficient_credits.

Example

curl -s -X POST https://api.goodtake.ai/v1/character \
  -H "Authorization: Bearer $GOODTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ava",
    "image_urls": [
      "https://example.com/1.jpg",
      "https://example.com/2.jpg",
      "https://example.com/3.jpg",
      "https://example.com/4.jpg"
    ],
    "include_outfits": true
  }' | jq -r .id

Errors

Status	Meaning
`400`	Malformed body, 0 or >20 `image_urls`, a non-`http(s)` scheme, or a URL resolving to an internal address
`401`	Missing or invalid API key
`503`	The generation model is disabled or unavailable