Skip to contentLaunch price until December 31 · 45 days left

Generations

A generation is one order: a prompt in, a video or an image out. Create it, then wait for it or check on it.

Create a generation

POST /v1/generations

curl https://api.tikiapi.com/v1/generations \
  -H "Authorization: Bearer $TIKIAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "Close-up of iced coffee being poured in slow motion, warm morning light",
    "duration": 10,
    "aspect_ratio": "9:16",
    "images": ["https://example.com/my-product.jpg"]
  }'

Body

FieldTypeRequiredDescription
modelstringYesModel id, for example seedance-2.5. See Models.
promptstringYesWhat to make. Up to 4,000 characters; English works best. For Seedance, name your references @Image1, @Video1.
durationintegerVideoLength in seconds, within the model's limits. You pay for exactly this many seconds.
aspect_ratiostringNoSeedance: 16:9, 9:16, 1:1, 4:3, 3:4 or 21:9. Nano Banana: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9 or 21:9; GPT Image 2.6 adds 9:21, 1:2, 2:1, 1:3 and 3:1. Seedream: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 or 21:9. Without it an image comes out square.
resolutionstringNoVideo: 720p or 1080p. Images: 1K, 2K or 4K (capital K). Must be one the model is sold in; GET /v1/models lists them.
imagesstring[]NoReference images as public https links or links from POST /v1/uploads (PNG, JPEG or WebP, up to 20 MB). How many depends on the model: GET /v1/models shows max_reference_images. For Seedance, name them in the prompt as @Image1, @Image2.
image_modestringNoSeedance: reference (default; images are references named @Image1), first_frame (the video starts on your 1 image) or first_last_frame (starts on the first of 2 images, ends on the second). GET /v1/models lists image_modes per model.
audiosstring[]NoSeedance: reference audio (voice, music, sound) as public https links to MP3 or WAV, or links from POST /v1/uploads, up to 15 MB. Name them @Audio1. Free. Seedance 2.5 takes audio on its own; 2.0 and Fast need an image or a video next to it. Not with frames. GET /v1/models shows max_reference_audios.
audiobooleanNoSeedance: false for a silent clip, same price. Default true. Where a model can't turn sound off (audio_optional is false) it's a 400.
videosstring[]NoReference videos (Seedance) as public https links to MP4 or MOV, or links from POST /v1/uploads, up to 50 MB each: up to 10 and 30 s in all for Seedance 2.5, up to 3 and 15 s for 2.0 and 2.0 Fast. 720p only. Billed per second over the clip's seconds plus the videos' seconds; GET /v1/models shows the price as with_video_usd.

Unknown fields are refused with 400 invalid_parameter, so a typo never goes unnoticed.

Response

202 with the order. price is what this video costs; it is reserved now and charged only if the video is ready.

{
  "id": "01a1d505-9092-76d6-aa18-ec5b3f2a65c6",
  "object": "generation",
  "model": "seedance-2.5",
  "kind": "video",
  "status": "queued",
  "mode": "live",
  "price": "0.84",
  "charged": "0.00",
  "input": { "prompt": "Close-up of iced coffee…", "aspect_ratio": "9:16", "resolution": null, "duration": 10, "images": 1 },
  "outputs": [],
  "error": null,
  "created_at": "2026-11-13T12:00:00.000Z",
  "finished_at": null,
  "eta_seconds": 130
}

Price an order first

POST /v1/generations/estimate takes the same body as an order (the prompt may be left out) and answers with the price for your account. Nothing is made and nothing is charged. Reference videos and audio are measured, since their seconds count.

curl https://api.tikiapi.com/v1/generations/estimate \
  -H "Authorization: Bearer $TIKIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "seedance-2.5", "duration": 10, "aspect_ratio": "9:16" }'
{
  "object": "estimate",
  "model": "seedance-2.5",
  "kind": "video",
  "mode": "live",
  "price": "0.84",
  "charge": "0.84",
  "available_balance": "12.50",
  "enough_balance": true,
  "can_order_now": true,
  "input": { "aspect_ratio": "9:16", "resolution": null, "duration": 10, "images": 0, "image_mode": null, "videos": 0, "video_seconds": 0, "audios": 0 }
}

charge is what the order would take from your balance: the price for a live key, 0.00 for a test key. enough_balance says whether the balance covers it now. An order the API would refuse gets the same error here, so an estimate is also a free check of the body. Estimates count towards the limit of 60 files a minute per key.

Use your own files

A picture, clip or sound on your computer becomes a link with POST /v1/uploads: send the file itself as the body. Use the url from the answer in images, videos or audios.

curl https://api.tikiapi.com/v1/uploads \
  -H "Authorization: Bearer $TIKIAPI_KEY" \
  --data-binary @photo.png
{
  "object": "upload",
  "kind": "image",
  "url": "https://…/inputs/…/up-3f9c….png?…",
  "content_type": "image/png",
  "bytes": 1843021,
  "expires_at": "2026-11-17T12:00:00.000Z"
}
  • Files: PNG, JPEG or WebP up to 20 MB; MP4 or MOV up to 50 MB; MP3 or WAV up to 15 MB. The type is read from the file itself, whatever the Content-Type header says. Clips and sounds come back with their duration in seconds.
  • Private: the link is signed and works for 48 hours (expires_at), then the file is deleted.
  • Errors: another kind of file is 400 invalid_parameter; a bigger one is 413 payload_too_large. The key needs the generations:write permission. Uploads count towards the limit of 60 files a minute per key.

Wait or poll

Two ways to get the result:

  • Poll. Call GET /v1/generations/{id} every 5–10 seconds until the status is final. Video usually takes longer than a minute. While the order runs, eta_seconds says about how many seconds are left, from this model's recent orders; it is null once the order is done.
  • Wait. Send Prefer: wait=60 with the create request. We hold the answer until the order is done, up to 60 seconds. If it is done, you get 200 with the result; if not, 202 and you poll as usual.

Statuses

StatusMeaning
queuedAccepted and waiting to start. The price is reserved on your balance.
runningThe model is making the video.
succeededDone. The video is in outputs, and the price is charged.
failedIt didn't work out. error says why. Nothing is charged.
canceledYou canceled it before it finished. Nothing is charged.

The result

{
  "id": "01a1d505-9092-76d6-aa18-ec5b3f2a65c6",
  "status": "succeeded",
  "price": "0.84",
  "charged": "0.84",
  "outputs": [
    {
      "url": "https://cdn.tikiapi.com/api/…/video.mp4",
      "content_type": "video/mp4",
      "bytes": 4810233,
      "duration": 10,
      "expires_at": "2026-12-13T12:01:40.000Z"
    }
  ],
  "finished_at": "2026-11-13T12:01:40.000Z"
}

Results are kept for 30 days: download what you need to keep. Each output's expires_at says when it goes; after that the link stops working. Sample outputs of test keys have expires_at: null.

Rather than checking until it's done, you can get a webhook: a signed POST to your server when the order succeeds or fails.

A failed order has "status": "failed" and an error with a code and a message, for example content_refused. Nothing is charged for it. See generation errors.

Retries without paying twice

Send an Idempotency-Key header with any unique string, such as your own order id. If the network drops and you send the same request again with the same key, you get the same order back instead of a second one. The same key with a different body is refused with 409 idempotency_key_reused.

List your generations

curl "https://api.tikiapi.com/v1/generations?limit=20" \
  -H "Authorization: Bearer $TIKIAPI_KEY"

Newest first, up to 100 per page. To get the next page, pass the next value from the response as before.

Cancel

curl -X POST https://api.tikiapi.com/v1/generations/GENERATION_ID/cancel \
  -H "Authorization: Bearer $TIKIAPI_KEY"

Cancels an order that hasn't finished and releases its price. A finished order can't be canceled: 409 not_cancelable.

Rate limits

Up to 60 new orders per minute per key. Above that you get 429 rate_limited with a Retry-After header in seconds.

NextWebhooks