POST /v1/generations

Make an image, clip, voice-over or music

Starts one generation. It spends credits, or runs on your own provider key: your provider bills you, and Kuro charges no credits. Pass `wait` to hold the response until it is ready (images usually are within a minute); otherwise read it with `GET /v1/generations/{id}`.

Permission

A key with chosen permissions needs generation.write. A key made with every permission may always call it. It can spend: send an Idempotency-Key so a retry replays the first answer.

Parameters

waitinteger · optional
Hold the response up to this many seconds until the work settles. 0 answers at once.
default 0 · min 0 · max 60
Idempotency-Key (header)string · optional
Any string up to 255 characters. Send the same value to retry a request without spending twice; a different body under a used key is refused with 409.
up to 255 characters

Body: type: "image"

type"image" · required
promptstring · optional
up to 2000 characters
modelstring · optional
Defaults to the server's default image model.
up to 80 characters
aspect_ratiostring · optional
Such as "9:16", "1:1" or "16:9". Defaults to 9:16, snapped to what the model offers.
up to 12 characters
settingstring · optional
The model's one extra setting (`setting` on `GET /v1/models/{id}`), such as its quality.
up to 40 characters
referencesMediaReference[] · optional
Pictures the model can see. The model's `max_reference_images` applies.
up to 16 items
subjectsstring[] · optional
Names or ids of your Subjects. Kuro brings each one's face and description, so do not also attach pictures of them.
up to 4 items
runs_onstring · optional
Who pays: "credits", or the vendor of one of your own keys ("replicate", "fal", …). Leave out to follow the payer order set in Settings → Agents.
up to 40 characters
webhook_urlstring · optional
Where to POST a signed event when this settles. HTTPS on the default port; see Webhooks in the API description.
up to 2048 characters · uri

Body: type: "clip"

type"clip" · required
promptstring · optional
up to 4000 characters
modelstring · optional
Defaults to the server's default clip model.
up to 80 characters
duration_secondsinteger · optional
One of the model's `duration.values`; -1 lets a model that supports it choose.
min -1 · max 60
resolutionstring · optional
up to 12 characters
aspect_ratiostring · optional
Defaults to 9:16. Leave out with a `first_frame`: the clip takes the frame's shape.
up to 12 characters
generate_audioboolean · optional
first_frameMediaReference · optional
A picture, clip or sound you already have in Kuro.
last_frameMediaReference · optional
A picture, clip or sound you already have in Kuro.
reference_imagesMediaReference[] · optional
up to 9 items
reference_videosMediaReference[] · optional
A take to copy motion from, or to re-sync a mouth in.
up to 3 items
reference_audiosMediaReference[] · optional
up to 3 items
subjectsstring[] · optional
Names or ids of your Subjects. Kuro brings each one's face and description, so do not also attach pictures of them.
up to 4 items
runs_onstring · optional
Who pays: "credits", or the vendor of one of your own keys ("replicate", "fal", …). Leave out to follow the payer order set in Settings → Agents.
up to 40 characters
webhook_urlstring · optional
Where to POST a signed event when this settles. HTTPS on the default port; see Webhooks in the API description.
up to 2048 characters · uri

Body: type: "voiceover"

type"voiceover" · required
textstring · required
The words to speak.
up to 4000 characters
subjectstring · optional
A Subject whose bound voice reads it. Then leave out model, voice, style_prompt and language_code.
up to 120 characters
modelstring · optional
up to 80 characters
voicestring · optional
A voice id from the model's `voices`.
up to 120 characters
style_promptstring · optional
How to say it, on models that take one.
up to 4000 characters
language_codestring · optional
up to 35 characters
speednumber · optional
min 0.1 · max 5
emotionstring · optional
up to 40 characters
runs_onstring · optional
Who pays: "credits", or the vendor of one of your own keys ("replicate", "fal", …). Leave out to follow the payer order set in Settings → Agents.
up to 40 characters
webhook_urlstring · optional
Where to POST a signed event when this settles. HTTPS on the default port; see Webhooks in the API description.
up to 2048 characters · uri

Body: type: "music"

type"music" · required
promptstring · required
The brief: genre, mood, instruments, tempo.
up to 4000 characters
modelstring · optional
up to 80 characters
lyricsstring · optional
up to 3500 characters
instrumentalboolean · optional
Defaults to true when there are no lyrics.
runs_onstring · optional
Who pays: "credits", or the vendor of one of your own keys ("replicate", "fal", …). Leave out to follow the payer order set in Settings → Agents.
up to 40 characters
webhook_urlstring · optional
Where to POST a signed event when this settles. HTTPS on the default port; see Webhooks in the API description.
up to 2048 characters · uri

Response: Generation

201 · One image, clip, voice-over or piece of music.

object"generation"
idstring
uuid
typestring
What was made. New values may be added; treat an unknown one as opaque.
one of "image", "clip", "voiceover", "music", "tool"
statusstring
`ready` and `failed` are final.
one of "queued", "generating", "ready", "failed"
modelstring
The model id it was made with (`GET /v1/models`).
promptstring
aspect_ratiostring | null
Null for audio.
output_urlstring | null
The finished file, once `ready`. A signed link that works for about an hour; read the generation again for a fresh one.
uri
thumbnail_urlstring | null
A small still of the result, for a grid. Null for audio and while it works.
uri
creditsnumber | null
Credits charged. Zero when your own provider key or the free allowance paid.
paid_bystring | null
Who paid: "credits", "house" (the free allowance), "server" (a server that charges nothing), or the vendor of your own key ("replicate", "fal", …).
errorstring | null
Why it failed. Null otherwise.
ready_in_secondsnumber | null
Roughly how long an unfinished generation has left; 0 means past its usual time.
recipe_idstring | null
The recipe it was made with, if any.
uuid
created_atstring
date-time
app_urlstring
Opens it in the app.
uri

Example

The required fields only, each a placeholder. Replace them before sending.

curl -X POST "https://api.meetkuro.com/v1/generations" \
  -H "Authorization: Bearer $KURO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"type":"image","prompt":"<prompt>"}'

import { Kuro } from "@meetkuro/sdk";

const kuro = new Kuro(); // reads KURO_API_KEY
await kuro.generations.createAndWait({ type: "image", prompt: "A lighthouse at dawn" });

Every operation