API reference / Generations

Create generation

POST/v1/generations

Submit an image or video generation. Returns immediately with a job id; poll the retrieve endpoint or wait for a webhook to learn the result.

Body parameters

Request body

productstringOptionalDefaults to kiara-image-pro

Public ID of the model to invoke. See the Models section for the catalog.

promptstringRequired

Text prompt that describes what to generate. 1–4000 characters. Be specific — subject, lighting, lens, mood, action.

negative_promptstringOptional

Things to avoid (e.g. `blurry, watermark, text`). Keep it short and concrete.

aspectstringOptionalDefaults to portrait

Output aspect ratio. `portrait` is best for character shots; `landscape` for scene compositions.

seedintegerOptional0 – 4,294,967,295

Deterministic seed. Same seed + same prompt = same image. Omit for a random seed.

webhook_urlurlOptional

HTTPS callback fired when the job reaches a terminal state. HMAC-SHA256 signed. See the Webhooks guide.

metadataobjectOptional

Arbitrary JSON object echoed back on retrieval and in the webhook. Useful for correlating jobs to your records. ≤ 4 KB.

The fields above cover text-to-image. Other models accept extra inputs: source_image_url and second_image_url for image-to-image edits, swaps, and outfit transfers; start_image_url for image-to-video; and duration_seconds, resolution, and generate_audio for video models. Each model's page lists exactly which inputs it requires.

Headers

Idempotency

Pass an Idempotency-Key header. Retrying with the same key + body returns the original job — no double-charge, no double-submit. Retrying with the same key + a different body returns 409 idempotency_conflict. Keys are scoped to your account and stored for the life of the job, so replays stay safe.

Returns

Response

Returns a generation object with these fields:

id— prefixed job id.
status— queued, processing, completed, failed, or canceled.
created_at— ISO-8601 timestamps; updated_at advances on each state change.
result.url— once completed, points to /v1/assets/{id}/content, which streams the asset bytes from the Kiara domain.
error.code— when failed, see Error codes.

Request

POSTCreate generation/v1/generations

curl https://api.kiara-api.com/v1/generations \
  -H "Authorization: Bearer $KIARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "product": "kiara-image-pro",
       "prompt": "studio portrait of a 24-year-old woman, soft window light, 85mm, shallow depth of field, natural skin texture"
     }'

Response · queued

{
  0: 1,
  2: 3,
  4: 5,
  6: 7,
  8: null,
  9: {
    10: 11
  }
}

Response · completed

{
  0: 1,
  2: 3,
  4: 5,
  6: 7,
  8: {
    9: 10,
    11: 12,
    13: 14,
    15: 1536,
    16: 2560
  },
  17: {
    18: 19
  }
}