API reference
Generated from the OpenAPI 3.1 document the API serves. Open a request or response to see its fields.
Models
What you can run and what it costs.
get/v1/models
· List modelsPublic, no keyEvery model open to the API right now, in display order: task type, params with their enum values and ranges, defaults, input limits and priceFromCoins (the coins of a request that sets only the prompt). Send only the params you want to set: omitted params take the model default. Public, cached for a minute.
Responses
200The catalog.
get/v1/effects
· List effectsPublic, no keyStyle filters and templates. Run one by quoting and submitting with its modelId and effectId; params then hold the effect input (images or video, and an optional prompt direction). Public.
Responses
200The effects.
Generations
Quote, start, follow and cancel generations.
post/v1/quotes
· Quote a generationScope: generatePrices a request exactly as a submit would. The quoteToken (valid 10 minutes) reserves exactly coins when you submit with it; after it expires the submit is accepted only at the same price (else price_changed).
Request body
application/json QuoteRequest
modelIdstringrequiredmin length 1
paramsobjectrequireddraftbooleandefault false
effectIdstringpattern ^[a-z0-9][a-z0-9-]{0,63}$
Responses
200The price.
400Invalid request: invalid_params, invalid_quote, idempotency_key_required, consent_required, input_too_large, input_duration, wrong_media…
401No valid key: unauthorized, invalid_api_key, api_key_revoked, api_key_expired.
403insufficient_scope, cooldown, account_locked.
404not_found or unknown_model.
429rate_limited: wait Retry-After seconds.
503unavailable, maintenance or channel_disabled: nothing was charged; retry later.
get/v1/generations
· List generationsScope: readYour generations, newest first, with cursor pagination: pass nextCursor back as cursor until it is null.
Parameters
cursorstringquerynextCursorof the previous page.limitintegerquery≥ 1 · ≤ 100 · default 30
statusstringqueryone of "queued", "processing", "succeeded", "failed", "canceled"
modalitystringqueryone of "image", "video", "audio", "3d"
workspacestringqueryone of "image", "video", "audio", "3d", "tools"
modelIdstringqueryactivebooleanqueryOnly generations that are still queued or processing.
Responses
200One page.
400Invalid request: invalid_params, invalid_quote, idempotency_key_required, consent_required, input_too_large, input_duration, wrong_media…
401No valid key: unauthorized, invalid_api_key, api_key_revoked, api_key_expired.
403insufficient_scope, cooldown, account_locked.
429rate_limited: wait Retry-After seconds.
post/v1/generations
· Start a generationScope: generateHolds the coins and queues the generation. Send exactly one of quoteToken (charge exactly the quoted coins) or maxCoins (charge the current price, refused with max_coins_exceeded above it): you are never charged more than either. The Idempotency-Key header is required: repeating a key with the same body returns the original generation (200); the same key with another body is idempotency_conflict (409). Failed generations are refunded in full; partial results are charged per delivered output.
Parameters
Idempotency-Keystringheaderrequiredmin length 16 · max length 128 · pattern ^[A-Za-z0-9_-]+$
16–128 characters of A–Z a–z 0–9 _ -, unique per intended generation (a UUID works). Scoped to your account.
Request body
application/json CreateGenerationRequest
modelIdstringrequiredmin length 1
paramsobjectrequiredquoteTokenstringmin length 1
maxCoinsinteger> 0
projectIdstring | nullmin length 1
effectIdstringpattern ^[a-z0-9][a-z0-9-]{0,63}$
consenttrue
Responses
200A replay of an earlier request with the same key.
201Created and queued.
400Invalid request: invalid_params, invalid_quote, idempotency_key_required, consent_required, input_too_large, input_duration, wrong_media…
401No valid key: unauthorized, invalid_api_key, api_key_revoked, api_key_expired.
402insufficient_coins, or spend_cap_exceeded for the key's monthly cap.
403insufficient_scope, cooldown, account_locked.
404not_found or unknown_model.
409idempotency_conflict, price_changed, max_coins_exceeded, not_cancelable.
429rate_limited: wait Retry-After seconds.
503unavailable, maintenance or channel_disabled: nothing was charged; retry later.
get/v1/generations/{id}
· Get a generationScope: readStatus (queued, processing, succeeded, failed, canceled), progress, coins and outputs. Output URLs are signed and short-lived: read the generation again for fresh ones. Prefer webhooks to polling; poll no faster than every 2 seconds.
Parameters
idstring (uuid)pathrequiredThe generation id.
Responses
200The generation.
401No valid key: unauthorized, invalid_api_key, api_key_revoked, api_key_expired.
403insufficient_scope, cooldown, account_locked.
404not_found or unknown_model.
429rate_limited: wait Retry-After seconds.
post/v1/generations/{id}/cancel
· Cancel a queued generationScope: generateFree, and only while the generation is still queued (not yet sent for processing); the held coins are released. Otherwise not_cancelable (409).
Parameters
idstring (uuid)pathrequiredThe generation id.
Responses
200Canceled.
401No valid key: unauthorized, invalid_api_key, api_key_revoked, api_key_expired.
403insufficient_scope, cooldown, account_locked.
404not_found or unknown_model.
409idempotency_conflict, price_changed, max_coins_exceeded, not_cancelable.
429rate_limited: wait Retry-After seconds.
Files
Input uploads and output files.
post/v1/uploads
· Upload an input fileScope: uploadsOne image (PNG, JPEG, WebP ≤ 20 MB, ≤ 8192 px), audio file (MP3, WAV, M4A, OGG ≤ 50 MB, ≤ 10 min) or video (MP4, WebM, MOV ≤ 200 MB, ≤ 60 s, ≤ 4096 px) as multipart/form-data in the field file. Use the returned id in a media param (image, images, first_frame, audio, video…). Uploads are deleted after 30 days.
Request body
multipart/form-data object
filestringrequiredOne of image/png, image/jpeg, image/webp, audio/mpeg, audio/wav, audio/mp4, audio/ogg, video/mp4, video/webm, video/quicktime.
Responses
201Stored.
400Invalid request: invalid_params, invalid_quote, idempotency_key_required, consent_required, input_too_large, input_duration, wrong_media…
401No valid key: unauthorized, invalid_api_key, api_key_revoked, api_key_expired.
403insufficient_scope, cooldown, account_locked.
413upload_too_large, upload_too_long.
415upload_invalid.
429rate_limited: wait Retry-After seconds.
503unavailable, maintenance or channel_disabled: nothing was charged; retry later.
get/v1/assets/{id}
· Get a fileScope: readAn output or upload with freshly signed, short-lived download URLs (about an hour).
Parameters
idstring (uuid)pathrequiredThe asset id.
Responses
200The file.
401No valid key: unauthorized, invalid_api_key, api_key_revoked, api_key_expired.
403insufficient_scope, cooldown, account_locked.
404not_found or unknown_model.
429rate_limited: wait Retry-After seconds.
Account
Balance and limits.
get/v1/generations/concurrency
· Running-generation limitScope: readHow many generations run at once for you, and how many run or wait now. Generations over the limit wait in the queue.
Responses
200The limit.
401No valid key: unauthorized, invalid_api_key, api_key_revoked, api_key_expired.
403insufficient_scope, cooldown, account_locked.
429rate_limited: wait Retry-After seconds.
get/v1/account
· Balance and limitsScope: accountYour coin balance, running-generation limit, rate limits and the calling key with its monthly spend.
Responses
200The account.
401No valid key: unauthorized, invalid_api_key, api_key_revoked, api_key_expired.
403insufficient_scope, cooldown, account_locked.
429rate_limited: wait Retry-After seconds.
Webhook events
Requests inker sends to your endpoints.
POST generation.succeeded
Sent to your endpoint when a generation ends this way. Verify Inker-Signature (t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>), refuse a t more than 300 s off, dedupe on Inker-Event-Id and answer 2xx within 10 s. Failed deliveries are retried for about a day.
application/json
idstringrequiredmin length 1
typestringrequiredone of "generation.succeeded", "generation.failed", "generation.canceled"
createdAtstring (date-time)requireddataobjectrequiredFields
- Generation
generationGenerationrequired
POST generation.failed
Sent to your endpoint when a generation ends this way. Verify Inker-Signature (t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>), refuse a t more than 300 s off, dedupe on Inker-Event-Id and answer 2xx within 10 s. Failed deliveries are retried for about a day.
application/json
idstringrequiredmin length 1
typestringrequiredone of "generation.succeeded", "generation.failed", "generation.canceled"
createdAtstring (date-time)requireddataobjectrequiredFields
- Generation
generationGenerationrequired
POST generation.canceled
Sent to your endpoint when a generation ends this way. Verify Inker-Signature (t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>), refuse a t more than 300 s off, dedupe on Inker-Event-Id and answer 2xx within 10 s. Failed deliveries are retried for about a day.
application/json
idstringrequiredmin length 1
typestringrequiredone of "generation.succeeded", "generation.failed", "generation.canceled"
createdAtstring (date-time)requireddataobjectrequiredFields
- Generation
generationGenerationrequired
Schemas
The objects the endpoints accept and return, each documented once.
Asset
idstringrequiredmin length 1 · max length 128 · pattern ^[A-Za-z0-9_-]+$
kindstringrequiredone of "image", "video", "audio", "3d", "text"
urlstringrequiredmin length 1
thumbnailUrlstringrequiredmin length 1
posterUrlstring | nullrequiredmin length 1
mimeTypestringrequiredmin length 1
widthinteger | nullrequired> 0
heightinteger | nullrequired> 0
durationSecondsnumber | nullrequired> 0
waveformUrlstring | nullmin length 1
transparentbooleandownloadsarray of objectFields
formatstringrequiredone of "obj", "fbx", "usdz", "stl"
urlstringrequiredmin length 1
bytesintegerrequired> 0
stemstring | nullone of "vocals", "drums", "bass", "other"
subtitlesobject | nullFields
srtUrlstringrequiredmin length 1
vttUrlstringrequiredmin length 1
Generation
idstringrequiredmin length 1
modelIdstringrequiredmin length 1
modelNamestringrequiredmin length 1
taskTypestringrequiredone of "image.generate", "image.edit", "video.generate", "video.animate", "image.upscale", "image.remove-bg", "image.inpaint", "image.outpaint", "image.relight", "image.vectorize", "image.restore", "image.effect", "video.v2v", "video.extend", "video.upscale", "video.interpolate", "video.remove-bg", "video.add-audio", "video.lipsync", "video.effect", "video.reframe", "audio.tts", "audio.music", "audio.sfx", "audio.voice-change", "audio.isolate", "audio.stt", "3d.from-text", "3d.from-image", "image.erase", "image.reframe", "image.sketch", "image.restyle", "image.colorize", "image.retouch", "image.product-shot", "image.replace-bg", "image.try-on"
modalitystringrequiredone of "image", "video", "audio", "3d"
workspacestringrequiredone of "image", "video", "audio", "3d", "tools"
effectobject | nullrequiredFields
idstringrequiredmin length 1
textstring | nullrequired
statusstringrequiredone of "queued", "processing", "succeeded", "failed", "canceled"
progressnumber | nullrequired≥ 0 · ≤ 1
queuePositioninteger | nullrequired> 0
paramsobjectrequiredcoinsQuotedintegerrequired> 0
coinsChargedinteger | nullrequired≥ 0
- Asset
outputsarray of Assetrequired outputsRequestedintegerrequired> 0
errorobject | nullrequiredFields
codestringrequiredone of "content_policy", "invalid_input", "unavailable", "timeout", "internal"
projectIdstring | nullrequiredmin length 1
createdAtstring (date-time)requiredstartedAtstring (date-time) | nullrequiredcompletedAtstring (date-time) | nullrequired
GenerationPage
- Generation
itemsarray of Generationrequired nextCursorstring | nullrequiredmin length 1
QuoteResponse
modelIdstringrequiredmin length 1
coinsintegerrequired> 0
coinsPerOutputintegerrequired> 0
outputsintegerrequired> 0
quoteTokenstring | nullrequiredmin length 1
expiresAtstring (date-time)requiredavailableCoinsintegerrequired≥ 0
Concurrency
limitintegerrequired> 0
raisedLimitinteger | nullrequired> 0
runningintegerrequired≥ 0
queuedintegerrequired≥ 0
PublicModelsResponse
modelsarray of objectrequiredFields
idstringrequiredmin length 1
listingIdstringrequiredmin length 1
taskTypestringrequiredone of "image.generate", "image.edit", "video.generate", "video.animate", "image.upscale", "image.remove-bg", "image.inpaint", "image.outpaint", "image.relight", "image.vectorize", "image.restore", "image.effect", "video.v2v", "video.extend", "video.upscale", "video.interpolate", "video.remove-bg", "video.add-audio", "video.lipsync", "video.effect", "video.reframe", "audio.tts", "audio.music", "audio.sfx", "audio.voice-change", "audio.isolate", "audio.stt", "3d.from-text", "3d.from-image", "image.erase", "image.reframe", "image.sketch", "image.restyle", "image.colorize", "image.retouch", "image.product-shot", "image.replace-bg", "image.try-on"
modalitystringrequiredone of "image", "video", "audio", "3d"
workspacestringrequiredone of "image", "video", "audio", "3d", "tools"
vendorstringrequiredmin length 1
displayNamestringrequiredmin length 1
paramsarray of object | object | object | object | object | objectrequiredFields
namestringrequiredone of "prompt", "negative_prompt", "aspect_ratio", "resolution", "duration", "num_outputs", "seed", "images", "image", "first_frame", "last_frame", "generate_audio", "upscale_factor", "mask", "expand_left", "expand_right", "expand_top", "expand_bottom", "video", "audio", "fps", "effect", "text", "voice", "language", "speed", "lyrics", "style", "instrumental", "stem", "polycount", "texture", "format", "garment", "lighting", "light_direction", "palette", "pbr", "quad", "geometry_quality", "texture_quality"
requiredbooleanrequireduiobjectrequiredFields
controlstringrequiredone of "prompt", "textarea", "aspect", "segmented", "select", "switch", "seed", "image", "images", "script", "lyrics", "tags", "voice", "language", "slider", "audio", "video", "mask", "expand", "effect"
groupstringrequiredone of "prompt", "inputs", "basic", "advanced"
orderintegerrequired
kind"text"requiredmaxLengthintegerrequired> 0
minLengthinteger> 0
Fields
namestringrequiredone of "prompt", "negative_prompt", "aspect_ratio", "resolution", "duration", "num_outputs", "seed", "images", "image", "first_frame", "last_frame", "generate_audio", "upscale_factor", "mask", "expand_left", "expand_right", "expand_top", "expand_bottom", "video", "audio", "fps", "effect", "text", "voice", "language", "speed", "lyrics", "style", "instrumental", "stem", "polycount", "texture", "format", "garment", "lighting", "light_direction", "palette", "pbr", "quad", "geometry_quality", "texture_quality"
requiredbooleanrequireduiobjectrequiredFields
controlstringrequiredone of "prompt", "textarea", "aspect", "segmented", "select", "switch", "seed", "image", "images", "script", "lyrics", "tags", "voice", "language", "slider", "audio", "video", "mask", "expand", "effect"
groupstringrequiredone of "prompt", "inputs", "basic", "advanced"
orderintegerrequired
kind"enum"requiredvaluesarray of string | number | booleanrequiredmin items 1
Fields
namestringrequiredone of "prompt", "negative_prompt", "aspect_ratio", "resolution", "duration", "num_outputs", "seed", "images", "image", "first_frame", "last_frame", "generate_audio", "upscale_factor", "mask", "expand_left", "expand_right", "expand_top", "expand_bottom", "video", "audio", "fps", "effect", "text", "voice", "language", "speed", "lyrics", "style", "instrumental", "stem", "polycount", "texture", "format", "garment", "lighting", "light_direction", "palette", "pbr", "quad", "geometry_quality", "texture_quality"
requiredbooleanrequireduiobjectrequiredFields
controlstringrequiredone of "prompt", "textarea", "aspect", "segmented", "select", "switch", "seed", "image", "images", "script", "lyrics", "tags", "voice", "language", "slider", "audio", "video", "mask", "expand", "effect"
groupstringrequiredone of "prompt", "inputs", "basic", "advanced"
orderintegerrequired
kind"range"requiredminnumberrequiredmaxnumberrequiredstepnumberrequired> 0
Fields
namestringrequiredone of "prompt", "negative_prompt", "aspect_ratio", "resolution", "duration", "num_outputs", "seed", "images", "image", "first_frame", "last_frame", "generate_audio", "upscale_factor", "mask", "expand_left", "expand_right", "expand_top", "expand_bottom", "video", "audio", "fps", "effect", "text", "voice", "language", "speed", "lyrics", "style", "instrumental", "stem", "polycount", "texture", "format", "garment", "lighting", "light_direction", "palette", "pbr", "quad", "geometry_quality", "texture_quality"
requiredbooleanrequireduiobjectrequiredFields
controlstringrequiredone of "prompt", "textarea", "aspect", "segmented", "select", "switch", "seed", "image", "images", "script", "lyrics", "tags", "voice", "language", "slider", "audio", "video", "mask", "expand", "effect"
groupstringrequiredone of "prompt", "inputs", "basic", "advanced"
orderintegerrequired
kind"seed"requiredmaxintegerrequired> 0
Fields
namestringrequiredone of "prompt", "negative_prompt", "aspect_ratio", "resolution", "duration", "num_outputs", "seed", "images", "image", "first_frame", "last_frame", "generate_audio", "upscale_factor", "mask", "expand_left", "expand_right", "expand_top", "expand_bottom", "video", "audio", "fps", "effect", "text", "voice", "language", "speed", "lyrics", "style", "instrumental", "stem", "polycount", "texture", "format", "garment", "lighting", "light_direction", "palette", "pbr", "quad", "geometry_quality", "texture_quality"
requiredbooleanrequireduiobjectrequiredFields
controlstringrequiredone of "prompt", "textarea", "aspect", "segmented", "select", "switch", "seed", "image", "images", "script", "lyrics", "tags", "voice", "language", "slider", "audio", "video", "mask", "expand", "effect"
groupstringrequiredone of "prompt", "inputs", "basic", "advanced"
orderintegerrequired
kind"media"requiredacceptstringrequiredone of "image", "audio", "video"
Fields
namestringrequiredone of "prompt", "negative_prompt", "aspect_ratio", "resolution", "duration", "num_outputs", "seed", "images", "image", "first_frame", "last_frame", "generate_audio", "upscale_factor", "mask", "expand_left", "expand_right", "expand_top", "expand_bottom", "video", "audio", "fps", "effect", "text", "voice", "language", "speed", "lyrics", "style", "instrumental", "stem", "polycount", "texture", "format", "garment", "lighting", "light_direction", "palette", "pbr", "quad", "geometry_quality", "texture_quality"
requiredbooleanrequireduiobjectrequiredFields
controlstringrequiredone of "prompt", "textarea", "aspect", "segmented", "select", "switch", "seed", "image", "images", "script", "lyrics", "tags", "voice", "language", "slider", "audio", "video", "mask", "expand", "effect"
groupstringrequiredone of "prompt", "inputs", "basic", "advanced"
orderintegerrequired
kind"media_list"requiredaccept"image"requiredminItemsintegerrequired≥ 0
maxItemsintegerrequired> 0
defaultsobjectrequiredpriceFromCoinsinteger | nullrequired> 0
inputLimitsobjectFields
maxOutputPixelsinteger> 0
maxOutputSideinteger> 0
minInputSecondsinteger> 0
maxInputSecondsinteger> 0
maxInputBytesinteger> 0
EffectsResponse
effectsarray of objectrequiredFields
idstringrequiredpattern ^[a-z0-9][a-z0-9-]{0,63}$
kindstringrequiredone of "image", "video"
categorystringrequiredone of "style", "template"
nameKeystringrequiredmin length 1
thumbnailstring | nullrequiredmin length 1
inputobject | objectrequiredFields
type"images"requiredminintegerrequired> 0
maxintegerrequired> 0
Fields
type"video"required
modelIdstringrequiredmin length 1
PublicAccount
balanceobjectrequiredFields
availableintegerrequiredheldintegerrequired≥ 0
- Concurrency
concurrencyConcurrencyrequired rateLimitsobjectrequiredFields
keyobjectrequiredFields
limitintegerrequired> 0
windowSecondsintegerrequired> 0
accountobjectrequiredFields
limitintegerrequired> 0
windowSecondsintegerrequired> 0
keyobject | nullrequiredFields
idstring (uuid)requiredpattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
namestringrequiredscopesarray of stringrequiredmonthlySpendCapCoinsinteger | nullrequired> 0
spentThisMonthCoinsintegerrequired≥ 0
expiresAtstring (date-time) | nullrequired
channelstringrequiredone of "web", "api", "mcp"
WebhookEvent
idstringrequiredmin length 1
typestringrequiredone of "generation.succeeded", "generation.failed", "generation.canceled"
createdAtstring (date-time)requireddataobjectrequiredFields
- Generation
generationGenerationrequired
Problem
typestringrequiredmin length 1
titlestringrequiredmin length 1
statusintegerrequired≥ 400 · ≤ 599
detailstringrequiredcodestringrequiredone of "invalid_params", "unknown_model", "invalid_quote", "price_changed", "max_coins_exceeded", "insufficient_coins", "idempotency_conflict", "idempotency_key_required", "cooldown", "account_locked", "unauthorized", "not_found", "not_cancelable", "rate_limited", "unavailable", "input_too_large", "input_duration", "input_file_too_large", "consent_required", "upload_too_large", "upload_invalid", "upload_too_long", "wrong_media", "download_too_large", "maintenance", "explore_blocked", "explore_limit", "explore_not_shareable", "explore_removed", "internal", "invalid_api_key", "api_key_revoked", "api_key_expired", "insufficient_scope", "channel_disabled", "spend_cap_exceeded"
instancestringissuesarray of objectFields
pathstringrequiredmessagestringrequired
QuoteRequest
modelIdstringrequiredmin length 1
paramsobjectrequireddraftbooleandefault false
effectIdstringpattern ^[a-z0-9][a-z0-9-]{0,63}$
CreateGenerationRequest
modelIdstringrequiredmin length 1
paramsobjectrequiredquoteTokenstringmin length 1
maxCoinsinteger> 0
projectIdstring | nullmin length 1
effectIdstringpattern ^[a-z0-9][a-z0-9-]{0,63}$
consenttrue