{"openapi":"3.1.0","info":{"title":"diffusr API","version":"2","summary":"Make videos, images and music over REST.","description":"Every call that makes something costs credits (1 credit = $0.01). Start with `dry_run: true` to get the price for free.\n\nMake calls answer at once with a job id; the work runs in the background. Poll GET /results/{id} until status is SUCCEEDED, FAILED or CANCELED, or pass `callback_url` to be told.\n\nAuthenticate with `Authorization: Bearer dfsr_live_…` (real) or `dfsr_test_…` (free, fake output, real prices). Keys come from the Developers page in the app.\n\nSend an `Idempotency-Key` on every make call so a retry never pays twice."},"servers":[{"url":"https://app.diffusr.ai/api/v2"}],"tags":[{"name":"Make"},{"name":"Results"},{"name":"Uploads"},{"name":"Models"},{"name":"Creators"},{"name":"Templates"},{"name":"Callbacks"},{"name":"Ads"}],"security":[{"bearerAuth":[]}],"paths":{"/make_video":{"post":{"operationId":"make_video","tags":["Make"],"summary":"Make a video from a prompt","description":"Starts a video job. Send `dry_run: true` first to get the price without spending. Video takes 1-10 minutes: poll GET /results/{id} or pass `callback_url`.\n\nNeeds the `generate` scope.\n\nPrice list: direct. Add `dry_run: true` to see the price without spending.","x-tariff":"direct","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1-255 visible ASCII characters you make up for this request (a UUID is fine). Send the same key to retry safely: you get the first job back instead of paying twice. Reusing a key for a different request answers 409 IDEMPOTENCY_CONFLICT. Wins over `idempotency_key` in the body.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x21-\\x7e]{1,255}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"description":"The shot: subject, action, camera, setting, sound."},"image_urls":{"description":"Optional reference pictures (a person, a product, a room, a first frame). Say in the prompt what each one is, by its place in this list — on Seedance: \"Image 1 is Mia, the speaker\". Public URLs — upload_asset gives you one for a local file.","type":"array","items":{"type":"string","minLength":1}},"audio_urls":{"description":"Optional voice or sound clips (models with takes_audio in list_models — the Seedance family). E.g. 5–10 s of the speaker's voice cut from an earlier clip, so the next clip keeps that voice. Name each in the prompt: \"Audio 1 is Mia's voice\". Public URLs.","type":"array","items":{"type":"string","minLength":1}},"duration_sec":{"description":"Length in seconds. Leave out for the model's default.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"aspect_ratio":{"description":"e.g. \"9:16\", \"16:9\", \"1:1\". Leave out for the model's default.","type":"string","minLength":1},"resolution":{"description":"e.g. \"720p\". Leave out for the model's default.","type":"string","minLength":1},"model":{"description":"Leave out for the recommended model. Ids come from list_models.","type":"string","minLength":1},"dry_run":{"description":"true = only check the request and return the price in credits. Nothing is made, nothing is spent.","type":"boolean"},"idempotency_key":{"description":"A unique string you make up for this request. Retry with the same key and you get the first result back instead of paying again.","type":"string","pattern":"^[\\x21-\\x7e]{1,255}$"},"callback_url":{"description":"Optional. A public https:// link. When the job finishes (done, failed or canceled) we POST the finished result here, signed. See the docs for checking the signature. Polling get_result still works.","type":"string","maxLength":2048}},"required":["prompt"]}}}},"responses":{"200":{"description":"dry_run was true: the price, nothing made, nothing spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiDryRun"}}}},"202":{"description":"The job started. Poll GET /results/{id}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiStarted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/make_image":{"post":{"operationId":"make_image","tags":["Make"],"summary":"Make an image from a prompt","description":"Starts an image job (about 10-30 seconds).\n\nNeeds the `generate` scope.\n\nPrice list: direct. Add `dry_run: true` to see the price without spending.","x-tariff":"direct","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1-255 visible ASCII characters you make up for this request (a UUID is fine). Send the same key to retry safely: you get the first job back instead of paying twice. Reusing a key for a different request answers 409 IDEMPOTENCY_CONFLICT. Wins over `idempotency_key` in the body.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x21-\\x7e]{1,255}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"description":"The picture: subject, setting, light, style."},"image_urls":{"description":"Optional reference pictures. Public URLs.","type":"array","items":{"type":"string","minLength":1}},"aspect_ratio":{"description":"e.g. \"9:16\", \"16:9\", \"1:1\". Leave out for the model's default.","type":"string","minLength":1},"resolution":{"description":"e.g. \"720p\". Leave out for the model's default.","type":"string","minLength":1},"model":{"description":"Leave out for the recommended model. Ids come from list_models.","type":"string","minLength":1},"dry_run":{"description":"true = only check the request and return the price in credits. Nothing is made, nothing is spent.","type":"boolean"},"idempotency_key":{"description":"A unique string you make up for this request. Retry with the same key and you get the first result back instead of paying again.","type":"string","pattern":"^[\\x21-\\x7e]{1,255}$"},"callback_url":{"description":"Optional. A public https:// link. When the job finishes (done, failed or canceled) we POST the finished result here, signed. See the docs for checking the signature. Polling get_result still works.","type":"string","maxLength":2048}},"required":["prompt"]}}}},"responses":{"200":{"description":"dry_run was true: the price, nothing made, nothing spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiDryRun"}}}},"202":{"description":"The job started. Poll GET /results/{id}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiStarted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/edit_image":{"post":{"operationId":"edit_image","tags":["Make"],"summary":"Edit a picture with a prompt","description":"Changes the picture in image_urls[0] as the prompt says.\n\nNeeds the `generate` scope.\n\nPrice list: direct. Add `dry_run: true` to see the price without spending.","x-tariff":"direct","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1-255 visible ASCII characters you make up for this request (a UUID is fine). Send the same key to retry safely: you get the first job back instead of paying twice. Reusing a key for a different request answers 409 IDEMPOTENCY_CONFLICT. Wins over `idempotency_key` in the body.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x21-\\x7e]{1,255}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"image_urls":{"minItems":1,"type":"array","items":{"type":"string","minLength":1},"description":"The picture to edit first, then any extra references. Public URLs."},"prompt":{"type":"string","maxLength":10000,"description":"What changes, and what stays. e.g. \"Make the can matte black. Keep the hand and the rain.\""},"aspect_ratio":{"description":"e.g. \"9:16\", \"16:9\", \"1:1\". Leave out for the model's default.","type":"string","minLength":1},"resolution":{"description":"e.g. \"720p\". Leave out for the model's default.","type":"string","minLength":1},"model":{"description":"Leave out for the recommended model. Ids come from list_models.","type":"string","minLength":1},"dry_run":{"description":"true = only check the request and return the price in credits. Nothing is made, nothing is spent.","type":"boolean"},"idempotency_key":{"description":"A unique string you make up for this request. Retry with the same key and you get the first result back instead of paying again.","type":"string","pattern":"^[\\x21-\\x7e]{1,255}$"},"callback_url":{"description":"Optional. A public https:// link. When the job finishes (done, failed or canceled) we POST the finished result here, signed. See the docs for checking the signature. Polling get_result still works.","type":"string","maxLength":2048}},"required":["image_urls","prompt"]}}}},"responses":{"200":{"description":"dry_run was true: the price, nothing made, nothing spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiDryRun"}}}},"202":{"description":"The job started. Poll GET /results/{id}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiStarted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/recast":{"post":{"operationId":"recast","tags":["Make"],"summary":"Recast a video clip","description":"Keeps a clip's motion, camera and timing and swaps who or what is in it. The price follows the clip's real length, read from the file.\n\nNeeds the `generate` scope.\n\nPrice list: outcome. Add `dry_run: true` to see the price without spending.","x-tariff":"outcome","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1-255 visible ASCII characters you make up for this request (a UUID is fine). Send the same key to retry safely: you get the first job back instead of paying twice. Reusing a key for a different request answers 409 IDEMPOTENCY_CONFLICT. Wins over `idempotency_key` in the body.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x21-\\x7e]{1,255}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"video_url":{"type":"string","minLength":1,"description":"The source clip, an MP4 or MOV link (upload_asset gives one). Its motion, camera and timing are kept. At most 10 s on the default model (30 s on seedance-2-5): a longer clip is refused before anything is spent, so trim it first. Its real length is read from the file and is what you are priced on."},"image_urls":{"description":"Photos of who or what should appear in the clip.","type":"array","items":{"type":"string","minLength":1}},"mode":{"description":"\"world\" = same motion, new people, place and look from the photos. \"swap\" = replace the main subject with the first photo, keep the rest. Use this OR prompt.","type":"string","enum":["world","swap"]},"prompt":{"description":"Your own instruction instead of a mode. Say the change, then what to keep.","type":"string","maxLength":10000},"duration_sec":{"description":"Ignored. The output length follows your clip's real length, read from video_url (rounded, within the model's range). It is also what you are priced on.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"aspect_ratio":{"description":"e.g. \"9:16\", \"16:9\", \"1:1\". Leave out for the model's default.","type":"string","minLength":1},"resolution":{"description":"e.g. \"720p\". Leave out for the model's default.","type":"string","minLength":1},"model":{"description":"Leave out for the recommended model. Ids come from list_models.","type":"string","minLength":1},"dry_run":{"description":"true = only check the request and return the price in credits. Nothing is made, nothing is spent.","type":"boolean"},"idempotency_key":{"description":"A unique string you make up for this request. Retry with the same key and you get the first result back instead of paying again.","type":"string","pattern":"^[\\x21-\\x7e]{1,255}$"},"callback_url":{"description":"Optional. A public https:// link. When the job finishes (done, failed or canceled) we POST the finished result here, signed. See the docs for checking the signature. Polling get_result still works.","type":"string","maxLength":2048}},"required":["video_url"]}}}},"responses":{"200":{"description":"dry_run was true: the price, nothing made, nothing spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiDryRun"}}}},"202":{"description":"The job started. Poll GET /results/{id}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiStarted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/creator_video":{"post":{"operationId":"creator_video","tags":["Make"],"summary":"Make a video of a creator saying a script","description":"A talking video from a creator in GET /creators. Gated preview.\n\nNeeds the `generate` scope.\n\nPrice list: outcome. Add `dry_run: true` to see the price without spending.","x-tariff":"outcome","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1-255 visible ASCII characters you make up for this request (a UUID is fine). Send the same key to retry safely: you get the first job back instead of paying twice. Reusing a key for a different request answers 409 IDEMPOTENCY_CONFLICT. Wins over `idempotency_key` in the body.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x21-\\x7e]{1,255}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"creator_id":{"type":"string","minLength":1,"description":"From list_creators."},"script":{"type":"string","maxLength":2000,"description":"What the creator says to camera, word for word. Length of the video follows the script."},"resolution":{"type":"string","enum":["480p","720p"]},"dry_run":{"description":"true = only check the request and return the price in credits. Nothing is made, nothing is spent.","type":"boolean"},"idempotency_key":{"description":"A unique string you make up for this request. Retry with the same key and you get the first result back instead of paying again.","type":"string","pattern":"^[\\x21-\\x7e]{1,255}$"},"callback_url":{"description":"Optional. A public https:// link. When the job finishes (done, failed or canceled) we POST the finished result here, signed. See the docs for checking the signature. Polling get_result still works.","type":"string","maxLength":2048}},"required":["creator_id","script"]}}}},"responses":{"200":{"description":"dry_run was true: the price, nothing made, nothing spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiDryRun"}}}},"202":{"description":"The job started. Poll GET /results/{id}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiStarted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/make_music":{"post":{"operationId":"make_music","tags":["Make"],"summary":"Make a song from a prompt","description":"One song, about a minute, on Lyria.\n\nNeeds the `generate` scope.\n\nPrice list: direct. Add `dry_run: true` to see the price without spending.","x-tariff":"direct","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1-255 visible ASCII characters you make up for this request (a UUID is fine). Send the same key to retry safely: you get the first job back instead of paying twice. Reusing a key for a different request answers 409 IDEMPOTENCY_CONFLICT. Wins over `idempotency_key` in the body.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x21-\\x7e]{1,255}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":10000,"description":"The song: genre, mood, instruments, tempo, and what it is for. Add lyrics with [Verse] / [Chorus] tags, or say \"Instrumental only, no vocals.\" Lyria picks the length (about a minute); a length in words is only a hint."},"dry_run":{"description":"true = only check the request and return the price in credits. Nothing is made, nothing is spent.","type":"boolean"},"idempotency_key":{"description":"A unique string you make up for this request. Retry with the same key and you get the first result back instead of paying again.","type":"string","pattern":"^[\\x21-\\x7e]{1,255}$"},"callback_url":{"description":"Optional. A public https:// link. When the job finishes (done, failed or canceled) we POST the finished result here, signed. See the docs for checking the signature. Polling get_result still works.","type":"string","maxLength":2048}},"required":["prompt"]}}}},"responses":{"200":{"description":"dry_run was true: the price, nothing made, nothing spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiDryRun"}}}},"202":{"description":"The job started. Poll GET /results/{id}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiStarted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/run_template":{"post":{"operationId":"run_template","tags":["Make"],"summary":"Run a template","description":"Runs one of the ready-made recipes from GET /templates (product ad, video template, talking head, podcast) as one job. Use `dry_run: true` for the price.\n\nNeeds the `generate` scope.\n\nPrice list: outcome. Add `dry_run: true` to see the price without spending.","x-tariff":"outcome","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1-255 visible ASCII characters you make up for this request (a UUID is fine). Send the same key to retry safely: you get the first job back instead of paying twice. Reusing a key for a different request answers 409 IDEMPOTENCY_CONFLICT. Wins over `idempotency_key` in the body.","schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x21-\\x7e]{1,255}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"template":{"type":"string","minLength":1,"description":"The template's id, from list_templates."},"mode":{"description":"Video templates only. \"remix\" (default) = make a new video like the template, from your pictures and prompt. \"recast\" = keep the template's moves and swap who is in it for your image_urls.","type":"string","enum":["remix","recast"]},"prompt":{"description":"Product ads: an optional change to the ad (\"make it a winter sale\"). Video templates: remix = your version of the template's prompt (leave out to use the template's own); recast = what to change.","type":"string","maxLength":10000},"pictures":{"description":"Video template remix: one picture per slot, keyed by the slot name from list_templates (e.g. {\"him\": \"https://…\"}).","type":"object","propertyNames":{"type":"string","minLength":1},"additionalProperties":{"type":"string","minLength":1}},"image_urls":{"description":"Video template recast: photos of who should appear in the clip.","maxItems":10,"type":"array","items":{"type":"string","minLength":1}},"product_image_url":{"description":"Product ads: a photo of your product, uploaded with upload_asset. Talking head: optional, shows the product on camera.","type":"string","minLength":1},"script":{"description":"Talking head: what the person says, word for word. Podcast: one line per turn, written \"Name: what they say\", the names exactly as in people. Everything must fit one 30 s take.","type":"string","maxLength":4000},"place":{"description":"Talking head: where they are, in a few words, e.g. \"a small Paris hotel room with a tall window\".","type":"string","maxLength":300},"people":{"description":"Talking head: one person. Podcast: two hosts, the first sits on the left.","maxItems":2,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40,"description":"What the script calls them, e.g. \"Mia\". Plain first names work best."},"image_url":{"type":"string","minLength":1,"description":"A clear photo of their face. A public link — upload_asset gives one for a local file."},"look":{"description":"Optional. Age, hair and outfit in a few words, e.g. \"30s, short dark hair, green jacket\". Leave out to keep what the photo shows.","type":"string","maxLength":300}},"required":["name","image_url"]}},"setup":{"description":"Talking head on the plain template: how it is filmed — \"selfie\" (default), \"propped\" or \"friend\".","type":"string","enum":["selfie","propped","friend"]},"resolution":{"description":"Leave out for the template's own default. 480p costs less.","type":"string","enum":["480p","720p"]},"dry_run":{"description":"true = only check the request and return the price in credits. Nothing is made, nothing is spent.","type":"boolean"},"idempotency_key":{"description":"A unique string you make up for this request. Retry with the same key and you get the first result back instead of paying again.","type":"string","pattern":"^[\\x21-\\x7e]{1,255}$"},"callback_url":{"description":"Optional. A public https:// link. When the job finishes (done, failed or canceled) we POST the finished result here, signed. See the docs for checking the signature. Polling get_result still works.","type":"string","maxLength":2048}},"required":["template"]}}}},"responses":{"200":{"description":"dry_run was true: the price, nothing made, nothing spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiDryRun"}}}},"202":{"description":"The job started. Poll GET /results/{id}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiStarted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/uploads":{"post":{"operationId":"upload_asset","tags":["Uploads"],"summary":"Upload a file to use as a reference","description":"Two ways in. Pass `source_url` (a public link) and we copy it. Or pass `content_type` + `size_bytes` for a local file: you get an `upload_url` to PUT the bytes to, then use `file_url` in a tool.\n\nNeeds the `uploads` scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source_url":{"description":"A public http(s) URL to copy in. Use this OR the three fields below.","type":"string","minLength":1},"content_type":{"description":"For a LOCAL file: its MIME type, e.g. \"video/mp4\", \"image/jpeg\".","type":"string","minLength":1},"size_bytes":{"description":"For a LOCAL file: its exact size in bytes.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}}}}},"responses":{"201":{"description":"A file_url (URL copied in), or an upload_url to PUT the bytes to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiUpload"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/results":{"get":{"operationId":"list_results","tags":["Results"],"summary":"List your recent jobs","description":"Needs the `results:read` scope.","parameters":[{"name":"limit","in":"query","required":false,"description":"Default 20.","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Your latest jobs, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResultList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/results/{id}":{"get":{"operationId":"get_result","tags":["Results"],"summary":"Get one job","description":"Status, output once it is done, and what it charged. Keep calling every 15-30 seconds until status is SUCCEEDED, FAILED or CANCELED. An id from the other key mode (test vs live) answers 404.\n\nNeeds the `results:read` scope.","parameters":[{"name":"id","in":"path","required":true,"description":"The job id from a make call.","schema":{"type":"string"}}],"responses":{"200":{"description":"The job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/results/{id}/cancel":{"post":{"operationId":"cancel_result","tags":["Results"],"summary":"Stop a job that has not finished","description":"`charge` on the answer says what was charged. Work that was not delivered is not charged.\n\nNeeds the `generate` scope.","parameters":[{"name":"id","in":"path","required":true,"description":"The job id from a make call.","schema":{"type":"string"}}],"responses":{"200":{"description":"The job after the cancel. A job that already finished comes back unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/models":{"get":{"operationId":"list_models","tags":["Models"],"summary":"List models and their prices","description":"Public: works without a key. With a key it counts toward your price-check limit.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["video","image"]}}],"responses":{"200":{"description":"The models you can pass as `model`, with prices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiModelList"}}}},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/creators":{"get":{"operationId":"list_creators","tags":["Creators"],"summary":"List creators for creator_video","description":"Gated preview: accounts not on the list get the 404 a bad URL gets.\n\nNeeds the `generate` scope.","responses":{"200":{"description":"Creators you can use in creator_video.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCreatorList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/templates":{"get":{"operationId":"list_templates","tags":["Templates"],"summary":"List the templates run_template can run","description":"Each template says what inputs it needs (name, type, required) and a rough price. Pass `dry_run: true` to run_template for the exact price.\n\nNeeds the `generate` scope.","responses":{"200":{"description":"Templates run_template can run, with the inputs each needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTemplateList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/callbacks":{"get":{"operationId":"list_callbacks","tags":["Callbacks"],"summary":"List callback deliveries","description":"Needs the `results:read` scope.","parameters":[{"name":"limit","in":"query","required":false,"description":"Default 20.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The next_cursor of the last page.","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Your callback delivery log, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCallbackDeliveryList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/callbacks/{event_id}/retry":{"post":{"operationId":"retry_callback","tags":["Callbacks"],"summary":"Retry a failed callback by hand","description":"Only for a FAILED event; at most 3 manual retries per event (else CALLBACK_NOT_RETRYABLE).\n\nNeeds the `results:read` scope.","parameters":[{"name":"event_id","in":"path","required":true,"description":"The callback event id (\"evt_…\").","schema":{"type":"string"}}],"responses":{"202":{"description":"The event, queued for another try.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCallbackDeliveryItem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/callbacks/secret":{"get":{"operationId":"get_callback_secret","tags":["Callbacks"],"summary":"Get your callback signing secret","description":"Needs the `results:read` scope.","responses":{"200":{"description":"Your signing secret (made on the first ask).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCallbackSecretView"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/callbacks/secret/rotate":{"post":{"operationId":"rotate_callback_secret","tags":["Callbacks"],"summary":"Make a new callback signing secret","description":"Needs the `results:read` scope.","responses":{"200":{"description":"The new secret. The old one keeps signing for 24 hours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCallbackSecretView"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/ads/accounts":{"get":{"operationId":"ads_list_accounts","tags":["Ads"],"summary":"List connected ad accounts","description":"Gated: accounts without ads get the 404 a bad URL gets.\n\nNeeds the `ads:read` scope.","responses":{"200":{"description":"Connected ad accounts and whether each is ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiAdsAccountList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/ads/creatives":{"get":{"operationId":"ads_list_creatives","tags":["Ads"],"summary":"List creatives you can advertise","description":"Needs the `ads:read` scope.","parameters":[{"name":"kind","in":"query","required":false,"description":"Leave out for both. TikTok takes videos only.","schema":{"type":"string","enum":["video","image"]}},{"name":"limit","in":"query","required":false,"description":"Default 40, newest first.","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Videos and pictures you can put in an ad.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiAdsCreativeList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/ads/campaigns":{"get":{"operationId":"ads_list_campaigns","tags":["Ads"],"summary":"List campaigns with stats","description":"Needs the `ads:read` scope.","parameters":[{"name":"days","in":"query","required":false,"description":"How many days of stats, counting today. Default 7.","schema":{"type":"integer","minimum":1,"maximum":30}}],"responses":{"200":{"description":"Campaigns with stats.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiAdsCampaigns"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/ads/launches":{"post":{"operationId":"ads_draft_launch","tags":["Ads"],"summary":"Draft an ad launch","description":"Makes a DRAFT only. Nothing launches or spends until a person opens review_url and presses Launch.\n\nNeeds the `ads:write` scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ad_account_id":{"type":"string","minLength":1,"description":"An id from ads_list_accounts. Its platform (Meta or TikTok) and currency come with it."},"name":{"description":"The campaign's name. Leave out for \"<account> · <date>\".","type":"string","minLength":1,"maxLength":120},"goal":{"type":"string","enum":["traffic","sales"],"description":"\"traffic\" = visits to a site; \"sales\" = purchases, needs pixel_id."},"pixel_id":{"description":"Sales only: the Meta pixel / TikTok pixel code to count purchases with.","type":"string","minLength":1},"daily_budget":{"type":"number","exclusiveMinimum":0,"description":"What the whole launch may spend a day, in the account's currency as people say it: 20 = $20 a day."},"start_at":{"description":"Leave out to start as soon as it's approved.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"end_at":{"description":"Leave out to run until paused.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"countries":{"minItems":1,"maxItems":25,"type":"array","items":{"type":"string"},"description":"Two-letter country codes, like [\"US\", \"CA\"]."},"age_min":{"description":"Default 18.","type":"integer","minimum":18,"maximum":65},"age_max":{"description":"Default 65.","type":"integer","minimum":18,"maximum":65},"gender":{"description":"Default \"all\".","type":"string","enum":["all","female","male"]},"ads":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"creative_id":{"type":"string","pattern":"^(asset|take|captionVideo):.+$","description":"An id from ads_list_creatives."},"text":{"type":"string","minLength":1,"maxLength":2200,"description":"The ad's words over the video. TikTok allows 100 characters, Meta far more (first ~125 show)."},"headline":{"description":"Meta only, optional: the bold line under the video.","type":"string","maxLength":255},"cta":{"type":"string","enum":["learn_more","shop_now","sign_up","download","contact_us","book_now"],"description":"The button."},"url":{"type":"string","minLength":1,"description":"Where the button goes. Must start with https://."}},"required":["creative_id","text","cta","url"]},"description":"One ad per video or picture, each with its own words."}},"required":["ad_account_id","goal","daily_budget","countries","ads"]}}}},"responses":{"201":{"description":"A DRAFT with a review_url.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiAdsLaunch"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/ads/launches/{id}":{"get":{"operationId":"ads_get_launch","tags":["Ads"],"summary":"Get one ad launch","description":"Needs the `ads:read` scope.","parameters":[{"name":"id","in":"path","required":true,"description":"The job id from a make call.","schema":{"type":"string"}}],"responses":{"200":{"description":"The launch and where it stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiAdsLaunch"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"webhooks":{"result.finished":{"post":{"operationId":"callback_result_finished","summary":"A job you started with callback_url has finished","description":"We POST this once when the job is done, failed or canceled. Signed with Standard Webhooks (https://www.standardwebhooks.com): check `webhook-signature` (`v1,<base64 HMAC-SHA256 of \"{webhook-id}.{webhook-timestamp}.{raw body}\">`, key = the base64 part of your `whsec_…` secret from GET /callbacks/secret) and reject a `webhook-timestamp` more than 5 minutes old. Answer any 2xx. Other answers are retried; `webhook-id` stays the same across retries, so use it to ignore repeats. During a secret rotation the header carries two signatures; accept either.","parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"The event id (\"evt_…\")."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds when this attempt was signed."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Space-separated signatures, each `v1,<base64>`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiCallbackEvent"}}}},"responses":{"2XX":{"description":"Received."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your API key: `dfsr_live_…` for real runs, `dfsr_test_…` for free fake runs that return real prices."}},"headers":{"RequestId":{"description":"Id of this request. Send your own `X-Request-Id` to choose it.","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait before trying again.","schema":{"type":"integer"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong, in plain words."},"code":{"type":"string","description":"A stable machine code; see API_ERROR_CODES."},"request_id":{"type":"string","description":"Quote this to support. Also in the X-Request-Id header."},"issues":{"description":"VALIDATION_FAILED and PREFLIGHT_FAILED: each problem.","type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":{}}}},"required":["error","code","request_id"],"additionalProperties":{},"description":"Every error. `code` is stable and machine-readable; a client must accept a code it does not know. Quote `request_id` to support."},"ApiPrice":{"type":"object","properties":{"credits":{"type":"number","description":"The most this call costs, in whole credits (1 credit = $0.01)."},"usd":{"type":"string","description":"The same price in US dollars, e.g. \"0.0336\"."},"tariff":{"type":"string","enum":["direct","outcome"],"description":"\"direct\" = your prompt goes to the model as sent; \"outcome\" = a result we shape (Recast, creator video)."},"tariff_version":{"type":"string"},"expires_at":{"type":"string","description":"The quoted price holds until then (ISO time)."}},"required":["credits","usd","tariff","tariff_version","expires_at"],"additionalProperties":false},"ApiCallbackEvent":{"type":"object","properties":{"id":{"type":"string","description":"Unique per event (\"evt_…\"). Also the webhook-id header. Retries of one event keep it, so use it to ignore repeats."},"type":{"type":"string","enum":["result.finished"]},"created_at":{"type":"string","description":"When the event was made (ISO time)."},"data":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","RUNNING","SUCCEEDED","FAILED","CANCELED"]}},"required":["id","status"],"additionalProperties":{},"description":"The finished result, exactly as get_result returns it."}},"required":["id","type","created_at","data"],"additionalProperties":false},"ApiStarted":{"type":"object","properties":{"id":{"type":"string","description":"The job id. Poll GET /results/{id} with it, or wait for the callback."},"status":{"type":"string","description":"\"PENDING\" on a new start; the run's current status when a retried Idempotency-Key replays the first job."},"credits_estimated":{"type":"number","description":"The most this job can cost, in credits."},"idempotent_replay":{"description":"true when this is the FIRST job again, answering a retried Idempotency-Key.","type":"boolean","const":true},"test":{"description":"true when a test key made the call: the price is real, nothing real ran. Absent for live keys.","type":"boolean","const":true},"price":{"description":"The price, locked in at start.","type":"object","properties":{"credits":{"type":"number","description":"The most this call costs, in whole credits (1 credit = $0.01)."},"usd":{"type":"string","description":"The same price in US dollars, e.g. \"0.0336\"."},"tariff":{"type":"string","enum":["direct","outcome"],"description":"\"direct\" = your prompt goes to the model as sent; \"outcome\" = a result we shape (Recast, creator video)."},"tariff_version":{"type":"string"},"expires_at":{"type":"string","description":"The quoted price holds until then (ISO time)."}},"required":["credits","usd","tariff","tariff_version","expires_at"],"additionalProperties":false},"duration_sec":{"type":"number"},"warnings":{"description":"Heads-ups that did not stop the call.","type":"array","items":{"type":"string"}},"next":{"type":"string","description":"What to do next, in words."}},"required":["id","status","credits_estimated","next"],"additionalProperties":false},"ApiDryRun":{"type":"object","properties":{"dry_run":{"type":"boolean","const":true},"test":{"description":"true when a test key made the call: the price is real, nothing real ran. Absent for live keys.","type":"boolean","const":true},"credits_estimated":{"type":"number"},"price":{"type":"object","properties":{"credits":{"type":"number","description":"The most this call costs, in whole credits (1 credit = $0.01)."},"usd":{"type":"string","description":"The same price in US dollars, e.g. \"0.0336\"."},"tariff":{"type":"string","enum":["direct","outcome"],"description":"\"direct\" = your prompt goes to the model as sent; \"outcome\" = a result we shape (Recast, creator video)."},"tariff_version":{"type":"string"},"expires_at":{"type":"string","description":"The quoted price holds until then (ISO time)."}},"required":["credits","usd","tariff","tariff_version","expires_at"],"additionalProperties":false},"duration_sec":{"type":"number"},"warnings":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}},"required":["dry_run","credits_estimated","note"],"additionalProperties":false},"ApiUpload":{"anyOf":[{"type":"object","properties":{"file_url":{"type":"string","description":"Pass this to a tool (image_urls / video_url / audio_urls)."},"kind":{"type":"string"},"next":{"type":"string"}},"required":["file_url","kind","next"],"additionalProperties":false},{"type":"object","properties":{"upload_url":{"type":"string","description":"PUT the file's bytes here."},"method":{"type":"string","const":"PUT"},"headers":{"type":"object","properties":{"Content-Type":{"type":"string"}},"required":["Content-Type"],"additionalProperties":false,"description":"Send these headers with the PUT."},"file_url":{"type":"string","description":"Works only after the PUT succeeds."},"kind":{"type":"string"},"expires_in_sec":{"type":"number"},"curl":{"type":"string","description":"The same PUT as a ready curl line."},"next":{"type":"string"}},"required":["upload_url","method","headers","file_url","kind","expires_in_sec","curl","next"],"additionalProperties":false}]},"ApiResultList":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","RUNNING","SUCCEEDED","FAILED","CANCELED"],"description":"PENDING and RUNNING = keep waiting. SUCCEEDED, FAILED and CANCELED are final."},"model":{"type":"string"},"credits_estimated":{"type":"number"},"created_at":{"type":"string"},"finished_at":{"type":"string"},"output":{"description":"Present once SUCCEEDED.","type":"object","properties":{"kind":{"type":"string","enum":["IMAGE","VIDEO","AUDIO"]},"url":{"type":"string","description":"Public link to the file."},"thumbnail_url":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"},"duration_sec":{"type":"number"}},"required":["kind","url"],"additionalProperties":false},"error":{"description":"Present when FAILED.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"request_id":{"description":"The X-Request-Id of the request that started the job.","type":"string"},"test":{"description":"true when a test key made the call: the price is real, nothing real ran. Absent for live keys.","type":"boolean","const":true},"charge":{"type":"object","properties":{"quoted_credits":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The most the call could charge (null for a run with no API quote)."},"charged_credits":{"type":"number","description":"What the call has charged so far. Work that was never delivered is not counted. A test run is always 0."},"final":{"type":"boolean","description":"true once the run is over: the number can no longer change."}},"required":["quoted_credits","charged_credits","final"],"additionalProperties":false},"price":{"type":"object","properties":{"credits":{"type":"number","description":"The most this call costs, in whole credits (1 credit = $0.01)."},"usd":{"type":"string","description":"The same price in US dollars, e.g. \"0.0336\"."},"tariff":{"type":"string","enum":["direct","outcome"],"description":"\"direct\" = your prompt goes to the model as sent; \"outcome\" = a result we shape (Recast, creator video)."},"tariff_version":{"type":"string"},"expires_at":{"type":"string","description":"The quoted price holds until then (ISO time)."}},"required":["credits","usd","tariff","tariff_version","expires_at"],"additionalProperties":false},"next":{"description":"Present while the job is not finished.","type":"string"}},"required":["id","status","model","created_at","charge"],"additionalProperties":false},"description":"Newest first."}},"required":["results"],"additionalProperties":false},"ApiResult":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","RUNNING","SUCCEEDED","FAILED","CANCELED"],"description":"PENDING and RUNNING = keep waiting. SUCCEEDED, FAILED and CANCELED are final."},"model":{"type":"string"},"credits_estimated":{"type":"number"},"created_at":{"type":"string"},"finished_at":{"type":"string"},"output":{"description":"Present once SUCCEEDED.","type":"object","properties":{"kind":{"type":"string","enum":["IMAGE","VIDEO","AUDIO"]},"url":{"type":"string","description":"Public link to the file."},"thumbnail_url":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"},"duration_sec":{"type":"number"}},"required":["kind","url"],"additionalProperties":false},"error":{"description":"Present when FAILED.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"request_id":{"description":"The X-Request-Id of the request that started the job.","type":"string"},"test":{"description":"true when a test key made the call: the price is real, nothing real ran. Absent for live keys.","type":"boolean","const":true},"charge":{"type":"object","properties":{"quoted_credits":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"The most the call could charge (null for a run with no API quote)."},"charged_credits":{"type":"number","description":"What the call has charged so far. Work that was never delivered is not counted. A test run is always 0."},"final":{"type":"boolean","description":"true once the run is over: the number can no longer change."}},"required":["quoted_credits","charged_credits","final"],"additionalProperties":false},"price":{"type":"object","properties":{"credits":{"type":"number","description":"The most this call costs, in whole credits (1 credit = $0.01)."},"usd":{"type":"string","description":"The same price in US dollars, e.g. \"0.0336\"."},"tariff":{"type":"string","enum":["direct","outcome"],"description":"\"direct\" = your prompt goes to the model as sent; \"outcome\" = a result we shape (Recast, creator video)."},"tariff_version":{"type":"string"},"expires_at":{"type":"string","description":"The quoted price holds until then (ISO time)."}},"required":["credits","usd","tariff","tariff_version","expires_at"],"additionalProperties":false},"next":{"description":"Present while the job is not finished.","type":"string"}},"required":["id","status","model","created_at","charge"],"additionalProperties":false},"ApiModelList":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pass this as `model`."},"name":{"type":"string"},"kind":{"type":"string","enum":["video","image"]},"aspect_ratios":{"type":"array","items":{"type":"string"}},"resolutions":{"type":"array","items":{"type":"string"}},"duration_sec":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"default":{"type":"number"}},"required":["min","max","default"],"additionalProperties":false},"max_reference_images":{"type":"number"},"takes_video":{"type":"boolean"},"takes_audio":{"type":"boolean","description":"Takes voice or sound clips in audio_urls."},"reference_labels":{"type":"object","properties":{"image":{"type":"string"},"video":{"type":"string"},"audio":{"type":"string"}},"additionalProperties":false},"cost":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"perImage"},"creditsPerImage":{"type":"number"},"approximate":{"type":"boolean"}},"required":["kind","creditsPerImage"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"perSecond"},"creditsPerSecond":{"type":"number"},"approximate":{"type":"boolean"}},"required":["kind","creditsPerSecond"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"perCall"},"creditsPerCall":{"type":"number"},"approximate":{"type":"boolean"}},"required":["kind","creditsPerCall"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"perCharacter"},"creditsPer100Chars":{"type":"number"},"approximate":{"type":"boolean"}},"required":["kind","creditsPer100Chars"],"additionalProperties":false}],"description":"The price as a simple number, at the API direct tariff."},"price":{"type":"object","properties":{"unit":{"type":"string","enum":["second","image"]},"credits":{"type":"number","description":"Credits per second of video, or per image, at the settings in `at`."},"at":{"type":"object","properties":{"aspect_ratio":{"type":"string"},"resolution":{"type":"string"},"duration_sec":{"type":"number"}},"required":["aspect_ratio"],"additionalProperties":false},"by_resolution":{"description":"The same price at each resolution, when the model has several.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"tariff":{"type":"string","const":"direct"},"tariff_version":{"type":"string"}},"required":["unit","credits","at","tariff","tariff_version"],"additionalProperties":false},"about":{"type":"string"},"caveat":{"type":"string"}},"required":["id","name","kind","aspect_ratios","max_reference_images","takes_video","takes_audio","cost","price"],"additionalProperties":false}}},"required":["models"],"additionalProperties":false},"ApiCreatorList":{"type":"object","properties":{"creators":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pass this as creator_id to creator_video."},"name":{"type":"string"},"blurb":{"type":"string"},"poster_url":{"type":"string"}},"required":["id","name","blurb","poster_url"],"additionalProperties":false}}},"required":["creators"],"additionalProperties":false},"ApiTemplateList":{"type":"object","properties":{"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pass this as `template` to run_template."},"name":{"type":"string"},"kind":{"type":"string","enum":["product_ad","video_template","talking_head","podcast"]},"about":{"type":"string"},"inputs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The run_template field this fills (a dotted name like `pictures.<slot>` is a key inside that field)."},"type":{"type":"string","description":"What it takes, e.g. \"text\", \"image_url\", \"video_url\", \"image_urls\"."},"required":{"type":"boolean"},"about":{"type":"string"}},"required":["name","type","required","about"],"additionalProperties":false}},"price_hint":{"description":"A rough price. The exact one comes from run_template with dry_run: true.","type":"object","properties":{"credits":{"type":"number"},"approximate":{"type":"boolean","const":true}},"required":["credits","approximate"],"additionalProperties":false}},"required":["id","name","kind","about","inputs"],"additionalProperties":false}}},"required":["templates"],"additionalProperties":false},"ApiCallbackDeliveryList":{"type":"object","properties":{"deliveries":{"type":"array","items":{"type":"object","properties":{"event_id":{"type":"string"},"type":{"type":"string","enum":["result.finished"]},"result_id":{"type":"string","description":"The job this event is about."},"url":{"type":"string"},"status":{"type":"string","enum":["PENDING","DELIVERED","FAILED"],"description":"PENDING = will be tried (again); DELIVERED = your server answered 2xx; FAILED = we gave up."},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"last_status_code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"last_error":{"type":"string"},"last_attempt_at":{"type":"string"},"next_attempt_at":{"type":"string"},"delivered_at":{"type":"string"},"created_at":{"type":"string"},"test":{"type":"boolean","const":true}},"required":["event_id","type","result_id","url","status","attempts","created_at"],"additionalProperties":false},"description":"Newest first."},"next_cursor":{"description":"Pass as `cursor` for the next page. Absent on the last page.","type":"string"}},"required":["deliveries"],"additionalProperties":false},"ApiCallbackDeliveryItem":{"type":"object","properties":{"event_id":{"type":"string"},"type":{"type":"string","enum":["result.finished"]},"result_id":{"type":"string","description":"The job this event is about."},"url":{"type":"string"},"status":{"type":"string","enum":["PENDING","DELIVERED","FAILED"],"description":"PENDING = will be tried (again); DELIVERED = your server answered 2xx; FAILED = we gave up."},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"last_status_code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"last_error":{"type":"string"},"last_attempt_at":{"type":"string"},"next_attempt_at":{"type":"string"},"delivered_at":{"type":"string"},"created_at":{"type":"string"},"test":{"type":"boolean","const":true}},"required":["event_id","type","result_id","url","status","attempts","created_at"],"additionalProperties":false},"ApiCallbackSecretView":{"type":"object","properties":{"secret":{"type":"string","description":"Starts with \"whsec_\". Use it to check the webhook-signature header."},"previous_valid_until":{"description":"After a rotation, the old secret still signs (a second signature) until this time.","type":"string"}},"required":["secret"],"additionalProperties":false},"ApiAdsAccountList":{"type":"object","properties":{"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"ready":{"type":"boolean"},"needs":{"anyOf":[{"type":"string"},{"type":"null"}]},"runs_as":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","platform","name","currency","ready","needs","runs_as"],"additionalProperties":false}},"settings_url":{"type":"string"},"next":{"type":"string"}},"required":["accounts","settings_url","next"],"additionalProperties":false},"ApiAdsCreativeList":{"type":"object","properties":{"creatives":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["image","video"]},"url":{"type":"string"},"thumbnail_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"width":{"anyOf":[{"type":"number"},{"type":"null"}]},"height":{"anyOf":[{"type":"number"},{"type":"null"}]},"duration_sec":{"anyOf":[{"type":"number"},{"type":"null"}]},"created_at":{"type":"string"},"fits":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","kind","url","thumbnail_url","width","height","duration_sec","created_at","fits"],"additionalProperties":false}}},"required":["creatives"],"additionalProperties":false},"ApiAdsCampaigns":{"type":"object","properties":{},"additionalProperties":{},"description":"Campaigns with their stats for the days asked."},"ApiAdsLaunch":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"step":{"anyOf":[{"type":"string"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"platform":{"type":"string"},"account":{"type":"string"},"name":{"type":"string"},"daily_budget":{"type":"number"},"currency":{"type":"string"},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"open_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"live_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"next":{"type":"string"}},"required":["id","status","step","error","platform","account","name","daily_budget","currency","review_url","open_url","live_at","next"],"additionalProperties":false}},"responses":{"Unauthorized":{"description":"Missing, wrong, revoked or expired API key (code UNAUTHORIZED, KEY_REVOKED, KEY_EXPIRED).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"Not enough credits, or an API budget would be passed (INSUFFICIENT_CREDITS, BUDGET_EXCEEDED).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The key may not do this (SCOPE_DENIED, MODEL_NOT_ALLOWED, TEST_MODE_UNSUPPORTED, ACCOUNT_BLOCKED, allowance_exceeded).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such id, or it is not yours, or it belongs to the other key mode (NOT_FOUND).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"IDEMPOTENCY_CONFLICT or CALLBACK_NOT_RETRYABLE.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooLarge":{"description":"The request or file is too large (TOO_LARGE, REFERENCE_TOO_LARGE).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unprocessable":{"description":"The request is not valid (VALIDATION_FAILED, INVALID_JSON, PREFLIGHT_FAILED, CALLBACK_URL_INVALID, REFERENCE_*). `issues` lists each problem. Nothing was charged.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests or jobs (RATE_LIMITED, CONCURRENCY_LIMIT, UPLOAD_QUOTA, …). Wait Retry-After seconds, then retry.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Our fault (INTERNAL_ERROR). Quote request_id to support.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Paused or busy (API_PAUSED, MODEL_PAUSED, PROVIDER_PAUSED, PROVIDER_BUSY, UNAVAILABLE). Wait Retry-After seconds, then retry.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"x-error-codes":{"UNAUTHORIZED":"Missing, malformed or unknown API key.","KEY_REVOKED":"This key was revoked. Make a new one on the Developers page.","KEY_EXPIRED":"This key passed its expiry date. Make a new one.","SCOPE_DENIED":"The key does not have the scope this call needs.","MODEL_NOT_ALLOWED":"The key is limited to other models.","TEST_MODE_UNSUPPORTED":"This call is not available with a test key.","ACCOUNT_BLOCKED":"The account is blocked. Contact support.","FORBIDDEN":"Not allowed (a refusal that has no more specific code).","VALIDATION_FAILED":"The input did not match the schema; `issues` lists each field and why. Nothing was made, nothing charged.","INVALID_JSON":"The body was not a JSON object.","INVALID_REQUEST":"The request was understood but cannot be done as sent (a refusal that has no more specific code).","PREFLIGHT_FAILED":"The job cannot run as described (for example a missing input); `issues` lists why. Nothing was charged.","CALLBACK_URL_INVALID":"callback_url is not usable: it must be a public https address with no password.","CALLBACK_NOT_RETRYABLE":"That callback event can't be retried now: it was delivered, is still being tried, or is out of manual retries.","REFERENCE_UNREACHABLE":"A reference file could not be fetched.","REFERENCE_TOO_LARGE":"A reference file is over the model's size or length limit.","REFERENCE_UNSUPPORTED":"A reference file is the wrong kind for this model.","REFERENCE_FORBIDDEN":"A reference points at a file the caller may not use.","NOT_FOUND":"No such id, or it belongs to someone else (or to the other key mode: test vs live).","IDEMPOTENCY_CONFLICT":"This Idempotency-Key was already used for a different request.","CONFLICT":"The request conflicts with the current state (a refusal that has no more specific code).","INSUFFICIENT_CREDITS":"Not enough free credits; `needed` and `balance` say by how much.","allowance_exceeded":"A team member's limit or the team pot is used up (legacy lowercase code, kept for existing clients).","BUDGET_EXCEEDED":"The key's or account's daily or monthly API budget would be passed; `budget` has the window and when it frees up.","RATE_LIMITED":"Too many requests of this kind this minute.","CONCURRENCY_LIMIT":"Too many jobs queued or running for this key or account.","PROVIDER_BUSY":"Our capacity at the model's supplier is full. Not the caller's fault; try again.","AUTH_RATE_LIMITED":"Too many failed sign-in attempts from this address.","KEY_LIMIT":"The key hit its own limit (for example how many keys an account may hold).","TEST_LIMIT":"A test key hit its own cap (per minute or per day). Wait, or use a live key.","UPLOAD_QUOTA":"Too many uploads in the last 24 hours.","STORAGE_QUOTA":"The account's stored upload bytes are at the cap; uploads clear on their own.","TOO_LARGE":"The request or file is too large (a refusal that has no more specific code).","WALLET_BUSY":"The wallet was locked by another request. Retry at once.","API_PAUSED":"New API starts are paused for everyone. Runs already started finish.","MODEL_PAUSED":"This model is paused for new API starts.","PROVIDER_PAUSED":"This model's supplier is paused for new API starts.","UNAVAILABLE":"A service we depend on is not available right now (a refusal that has no more specific code). Retry later.","INTERNAL_ERROR":"Something went wrong on our side. Quote the request_id to support."}}