Kinoseed

Behaviour

Idempotency

A POST that times out leaves you not knowing whether the run started and was charged. With an Idempotency-Key you send it again and find out, without paying twice.

How it works

  1. Add Idempotency-Key: any-string-you-choose (up to 255 characters) to POST /images or POST /videos. Derive it from your own data, like an order id, so a retry naturally sends the same one.
  2. The key is claimed before anything is charged. The first request runs as normal and its response is stored for 24 hours.
  3. Send the same key with the same body again and you get that stored response back, same job id, with Idempotent-Replayed: true. No second run, no second charge. Then poll the job as usual.
curl -X POST https://kinoseed.app/api/v1/images \
  -H "Authorization: Bearer ks_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-hero" \
  -d '{
    "prompt": "a ceramic mug on a sunlit desk, product photo",
    "model": "nano-banana-pro",
    "aspect": "1:1",
    "count": 2
  }'

The other answers

SituationAnswer
The first request with this key is still running409 idempotency_in_flight
Same key, different body (within 24 hours)422 idempotency_mismatch
The first attempt was refused (402, 429, a 5xx)The key is released: fix the cause and send the very same request again.
More than 24 hours laterThe key is forgotten and the request runs as new.

Keys are per account, so two of your scripts must not share one for different work. Only POST /images and POST /videos read the header: quoting, reading, deleting and uploading charge nothing and are safe to repeat as they are. See Errors for the envelope.