{"openapi":"3.1.0","info":{"title":"Voiser API","version":"2.0.0","description":"Text to speech, transcription, dubbing, voice cloning, music and video generation. Authenticate with `Authorization: Bearer <API key>`."},"servers":[{"url":"https://api.34.181.188.80.sslip.io"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Account","description":"Plan and credit balance of the account the API key belongs to."},{"name":"Voices","description":"The voice library: hundreds of voices in many languages, plus your voice clones."},{"name":"Text to speech","description":"Turn text into natural speech."},{"name":"Text to speech projects","description":"Long-form narration (audiobooks, courses) as projects shared with the studio."},{"name":"Transcription","description":"Speech to text with speaker labels, translation, summaries and exports."},{"name":"Dubbing","description":"Translate and re-voice videos into other languages."},{"name":"Voice cloning","description":"Create a voice from your own recordings (with verified consent)."},{"name":"Music","description":"Generate royalty-free songs and instrumentals."},{"name":"Video","description":"Generate videos from text or images."},{"name":"Files","description":"Upload inputs and download outputs."},{"name":"Jobs","description":"Every generation runs as a job. Poll it or receive a webhook."}],"paths":{"/v2/account":{"get":{"operationId":"getAccount","tags":["Account"],"summary":"Get account, plan and credit balance","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["personal","team"]},"plan":{"type":"object","properties":{"code":{"type":"string"},"source":{"type":"string"},"ends_at":{"type":["string","null"]}},"required":["code","source","ends_at"],"additionalProperties":false},"credits":{"type":"object","properties":{"available":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"subscription":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"packs":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bonus":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"held":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"next_expiry_at":{"type":["string","null"]}},"required":["available","subscription","packs","bonus","held","next_expiry_at"],"additionalProperties":false}},"required":["id","type","plan","credits"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/voices":{"get":{"operationId":"listVoices","tags":["Voices"],"summary":"List voices","description":"Voices of the library. Filter by language, gender, quality and more. Paginate with `cursor`.","parameters":[{"name":"language","in":"query","required":false,"schema":{"type":"string","enum":["tr","en","de","es","fr","it","pt","ru","ja","pl","nl","hi"]},"description":"BCP-47 language code (e.g. `tr-TR`, `en-US`)"},{"name":"gender","in":"query","required":false,"schema":{"type":"string","enum":["male","female","neutral","child"]}},{"name":"quality","in":"query","required":false,"schema":{"type":"string","enum":["standard","premium"]}},{"name":"age","in":"query","required":false,"schema":{"type":"string","enum":["child","young","adult","senior"]}},{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":60}},{"name":"expressive","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}},{"name":"include_legacy","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"Include legacy voices migrated from the previous platform"},{"name":"available","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"Only voices your plan can use"},{"name":"ui_language","in":"query","required":false,"schema":{"type":"string","enum":["tr","en"]},"description":"Language of descriptions"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{1,6}$"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"languages":{"type":"array","items":{"type":"string"}},"multilingual":{"type":"boolean"},"accent":{"type":["string","null"]},"gender":{"type":["string","null"]},"age":{"type":["string","null"]},"tone":{"type":["string","null"]},"use_cases":{"type":"array","items":{"type":"string"}},"styles":{"type":"array","items":{"type":"string"}},"supports_emotion":{"type":"boolean"},"supports_instructions":{"type":"boolean"},"expressive":{"type":"boolean"},"quality":{"type":"string","enum":["standard","premium"]},"status":{"type":"string","enum":["active","legacy"]},"popular":{"type":"boolean"}},"required":["id","name","description","languages","multilingual","accent","gender","age","tone","use_cases","styles","supports_emotion","supports_instructions","expressive","quality","status","popular"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/voices/{voice_id}":{"get":{"operationId":"getVoice","tags":["Voices"],"summary":"Get a voice","parameters":[{"name":"voice_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"languages":{"type":"array","items":{"type":"string"}},"multilingual":{"type":"boolean"},"accent":{"type":["string","null"]},"gender":{"type":["string","null"]},"age":{"type":["string","null"]},"tone":{"type":["string","null"]},"use_cases":{"type":"array","items":{"type":"string"}},"styles":{"type":"array","items":{"type":"string"}},"supports_emotion":{"type":"boolean"},"supports_instructions":{"type":"boolean"},"expressive":{"type":"boolean"},"quality":{"type":"string","enum":["standard","premium"]},"status":{"type":"string","enum":["active","legacy"]},"popular":{"type":"boolean"}},"required":["id","name","description","languages","multilingual","accent","gender","age","tone","use_cases","styles","supports_emotion","supports_instructions","expressive","quality","status","popular"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/voices/{voice_id}/preview":{"get":{"operationId":"getVoicePreview","tags":["Voices"],"summary":"Get a voice preview","description":"Signed URL of a short MP3 sample of the voice.","parameters":[{"name":"voice_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"language","in":"query","required":false,"schema":{"type":"string","enum":["tr","en","de","es","fr","it","pt","ru","ja","pl","nl","hi"]},"description":"BCP-47 language code (e.g. `tr-TR`, `en-US`)"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"expires_at":{"type":"string"},"language":{"type":"string"}},"required":["url","expires_at","language"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/languages":{"get":{"operationId":"listLanguages","tags":["Voices"],"summary":"List languages with voices","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"voice_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["code","voice_count"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/files":{"post":{"operationId":"createFile","tags":["Files"],"summary":"Create an upload","description":"Registers a file and returns an upload URL. Send the bytes with `PUT` to `upload.url` (with `upload.headers`), then call `POST /v2/files/{id}/complete`. Large files can be sent in chunks with `Content-Range`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"mime":{"type":"string","minLength":3,"maxLength":120,"description":"MIME type of the file (e.g. `audio/mpeg`, `video/mp4`, `image/png`)"},"bytes":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Exact file size in bytes"},"purpose":{"default":"input","type":"string","enum":["input","reference","first_frame","last_frame","document"]}},"required":["mime","bytes"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"file"},"kind":{"type":"string"},"status":{"type":"string","enum":["pending","ready","rejected"]},"name":{"type":["string","null"]},"mime":{"type":"string"},"bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"duration_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string"},"job_id":{"type":["string","null"]},"created_at":{"type":"string"},"expires_at":{"type":["string","null"]},"download_url":{"description":"Signed URL valid for 15 minutes; null unless the file is ready","type":["string","null"]},"download_expires_at":{"type":["string","null"]}},"required":["id","object","kind","status","name","mime","bytes","duration_ms","width","height","source","job_id","created_at","expires_at","download_url","download_expires_at"],"additionalProperties":false},"upload":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","const":"PUT"},"headers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"resumable":{"type":"boolean"},"chunk_bytes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"expires_at":{"type":"string"}},"required":["url","method","headers","resumable","chunk_bytes","expires_at"],"additionalProperties":false}},"required":["file","upload"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}]}},"/v2/files/{file_id}/complete":{"post":{"operationId":"completeFile","tags":["Files"],"summary":"Complete an upload","description":"Verifies the uploaded bytes (type, size, duration). The file becomes `ready` or `rejected`.","parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"file"},"kind":{"type":"string"},"status":{"type":"string","enum":["pending","ready","rejected"]},"name":{"type":["string","null"]},"mime":{"type":"string"},"bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"duration_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string"},"job_id":{"type":["string","null"]},"created_at":{"type":"string"},"expires_at":{"type":["string","null"]},"download_url":{"description":"Signed URL valid for 15 minutes; null unless the file is ready","type":["string","null"]},"download_expires_at":{"type":["string","null"]}},"required":["id","object","kind","status","name","mime","bytes","duration_ms","width","height","source","job_id","created_at","expires_at","download_url","download_expires_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/files/import":{"post":{"operationId":"importFile","tags":["Files"],"summary":"Import a file from a URL","description":"Downloads audio or video from a public link (direct file, YouTube, social media). Free; runs as a job whose result has `file_id`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"},"name":{"type":"string","minLength":1,"maxLength":200},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"required":["url"],"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}]}},"/v2/files/{file_id}":{"get":{"operationId":"getFile","tags":["Files"],"summary":"Get a file and its download URL","parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"file"},"kind":{"type":"string"},"status":{"type":"string","enum":["pending","ready","rejected"]},"name":{"type":["string","null"]},"mime":{"type":"string"},"bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"duration_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"source":{"type":"string"},"job_id":{"type":["string","null"]},"created_at":{"type":"string"},"expires_at":{"type":["string","null"]},"download_url":{"description":"Signed URL valid for 15 minutes; null unless the file is ready","type":["string","null"]},"download_expires_at":{"type":["string","null"]}},"required":["id","object","kind","status","name","mime","bytes","duration_ms","width","height","source","job_id","created_at","expires_at","download_url","download_expires_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/jobs":{"get":{"operationId":"listJobs","tags":["Jobs"],"summary":"List jobs","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]}},{"name":"product","in":"query","required":false,"schema":{"type":"string","enum":["text_to_speech","transcription","dubbing","voice_clone","music","video"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/jobs/{job_id}":{"get":{"operationId":"getJob","tags":["Jobs"],"summary":"Get a job","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/jobs/{job_id}/cancel":{"post":{"operationId":"cancelJob","tags":["Jobs"],"summary":"Cancel a job","description":"Cancels a queued or running job. Held credits are released.","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/text-to-speech":{"post":{"operationId":"createSpeech","tags":["Text to speech"],"summary":"Convert text to speech","description":"Starts a job that turns text into an audio file. Poll `GET /v2/jobs/{id}` or pass `webhook_url`. The result has `file_id`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100000,"description":"Text to speak. Supports Voiser markup (pauses, emphasis, emotion tags)"},"voice_id":{"type":"string","pattern":"^(voice_[0-9A-Za-z]{12}|clone_[0-9a-f-]{36})$","description":"Voice id from `GET /v2/voices` (`voice_…`) or a voice clone (`clone_…`)"},"language":{"description":"Language of the text; defaults to the voice's language","type":"string","enum":["tr","en","de","es","fr","it","pt","ru","ja","pl","nl","hi"]},"format":{"default":"mp3","type":"string","enum":["mp3","wav"]},"settings":{"type":"object","properties":{"speed":{"description":"Speaking rate; 1 is normal","type":"number","minimum":0.5,"maximum":2},"pitch":{"description":"Pitch in semitones","type":"number","minimum":-12,"maximum":12},"volume":{"description":"Volume multiplier (voices that support it)","type":"number","minimum":0.1,"maximum":2},"emotion":{"description":"Emotion or style (e.g. `cheerful`, `calm`); see the voice's `styles`","type":"string","minLength":1,"maxLength":60},"emotion_intensity":{"type":"number","minimum":0.01,"maximum":2},"instructions":{"description":"Free-form direction (voices with `supports_instructions`)","type":"string","maxLength":500},"stability":{"type":"number","minimum":0,"maximum":1}},"additionalProperties":false,"description":"Voice settings"},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"required":["text","voice_id"],"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}]}},"/v2/text-to-speech/quote":{"post":{"operationId":"quoteSpeech","tags":["Text to speech"],"summary":"Estimate credits for text to speech","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":100000,"description":"Text to speak. Supports Voiser markup (pauses, emphasis, emotion tags)"},"voice_id":{"type":"string","pattern":"^(voice_[0-9A-Za-z]{12}|clone_[0-9a-f-]{36})$","description":"Voice id from `GET /v2/voices` (`voice_…`) or a voice clone (`clone_…`)"},"language":{"description":"Language of the text; defaults to the voice's language","type":"string","enum":["tr","en","de","es","fr","it","pt","ru","ja","pl","nl","hi"]},"format":{"default":"mp3","type":"string","enum":["mp3","wav"]},"settings":{"type":"object","properties":{"speed":{"description":"Speaking rate; 1 is normal","type":"number","minimum":0.5,"maximum":2},"pitch":{"description":"Pitch in semitones","type":"number","minimum":-12,"maximum":12},"volume":{"description":"Volume multiplier (voices that support it)","type":"number","minimum":0.1,"maximum":2},"emotion":{"description":"Emotion or style (e.g. `cheerful`, `calm`); see the voice's `styles`","type":"string","minLength":1,"maxLength":60},"emotion_intensity":{"type":"number","minimum":0.01,"maximum":2},"instructions":{"description":"Free-form direction (voices with `supports_instructions`)","type":"string","maxLength":500},"stability":{"type":"number","minimum":0,"maximum":1}},"additionalProperties":false,"description":"Voice settings"}},"required":["text","voice_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Credits the job will hold (upper bound; unused credits are released)"},"affordable":{"type":"boolean"},"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["credits","affordable","balance","details"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/tts-projects":{"get":{"operationId":"listTtsProjects","tags":["Text to speech projects"],"summary":"List text to speech projects","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}},{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"tts_project"},"name":{"type":"string"},"language":{"type":"string"},"voice_id":{"type":"string"},"characters":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"block_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"favorite":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","language","voice_id","characters","block_count","favorite","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createTtsProject","tags":["Text to speech projects"],"summary":"Create a project","description":"Creates a long-form project (it also appears in the studio). Text is split into chapters and blocks automatically; export it with `POST /v2/tts-projects/{id}/export`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"language":{"type":"string","enum":["tr","en","de","es","fr","it","pt","ru","ja","pl","nl","hi"],"description":"BCP-47 language code (e.g. `tr-TR`, `en-US`)"},"voice_id":{"type":"string","pattern":"^(voice_[0-9A-Za-z]{12}|clone_[0-9a-f-]{36})$","description":"Voice id from `GET /v2/voices` (`voice_…`) or a voice clone (`clone_…`)"},"text":{"type":"string","maxLength":2000000},"settings":{"type":"object","properties":{"speed":{"description":"Speaking rate; 1 is normal","type":"number","minimum":0.5,"maximum":2},"pitch":{"description":"Pitch in semitones","type":"number","minimum":-12,"maximum":12},"volume":{"description":"Volume multiplier (voices that support it)","type":"number","minimum":0.1,"maximum":2},"emotion":{"description":"Emotion or style (e.g. `cheerful`, `calm`); see the voice's `styles`","type":"string","minLength":1,"maxLength":60},"emotion_intensity":{"type":"number","minimum":0.01,"maximum":2},"instructions":{"description":"Free-form direction (voices with `supports_instructions`)","type":"string","maxLength":500},"stability":{"type":"number","minimum":0,"maximum":1}},"additionalProperties":false,"description":"Voice settings"}},"required":["name","language","voice_id"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"tts_project"},"name":{"type":"string"},"language":{"type":"string"},"voice_id":{"type":"string"},"characters":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"block_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"favorite":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"chapters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":["string","null"]},"block_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"characters":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","title","block_count","characters"],"additionalProperties":false}}},"required":["id","object","name","language","voice_id","characters","block_count","favorite","created_at","updated_at","chapters"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}]}},"/v2/tts-projects/import":{"post":{"operationId":"importTtsProject","tags":["Text to speech projects"],"summary":"Create a project from a document or web page","description":"Reads a DOCX, PDF, EPUB or TXT file (upload it first with `POST /v2/files`, purpose `document`) or a web article URL.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"type":"string","format":"uuid","pattern":"^([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)$"},"url":{"type":"string","maxLength":2000,"format":"uri"},"project_id":{"description":"Append to this project instead of creating one","type":"string","format":"uuid","pattern":"^([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)$"},"name":{"type":"string","minLength":1,"maxLength":120},"language":{"type":"string","enum":["tr","en","de","es","fr","it","pt","ru","ja","pl","nl","hi"],"description":"BCP-47 language code (e.g. `tr-TR`, `en-US`)"},"voice_id":{"type":"string","pattern":"^(voice_[0-9A-Za-z]{12}|clone_[0-9a-f-]{36})$","description":"Voice id from `GET /v2/voices` (`voice_…`) or a voice clone (`clone_…`)"}},"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"project_id":{"type":"string"},"chapter_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"block_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"characters":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"warnings":{"type":"array","items":{"type":"string"}},"truncated":{"type":"boolean"}},"required":["project_id","chapter_count","block_count","characters","warnings","truncated"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}]}},"/v2/tts-projects/{project_id}":{"get":{"operationId":"getTtsProject","tags":["Text to speech projects"],"summary":"Get a project","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"tts_project"},"name":{"type":"string"},"language":{"type":"string"},"voice_id":{"type":"string"},"characters":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"block_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"favorite":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"chapters":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":["string","null"]},"block_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"characters":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","title","block_count","characters"],"additionalProperties":false}}},"required":["id","object","name","language","voice_id","characters","block_count","favorite","created_at","updated_at","chapters"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/tts-projects/{project_id}/quote":{"get":{"operationId":"quoteTtsProjectExport","tags":["Text to speech projects"],"summary":"Estimate credits for exporting a project","description":"Only blocks that changed since the last generation are charged; cached blocks are free.","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"characters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"blocks_to_generate":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"blocks_cached":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["credits","characters","blocks_to_generate","blocks_cached"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/tts-projects/{project_id}/export":{"post":{"operationId":"exportTtsProject","tags":["Text to speech projects"],"summary":"Export a project to audio","description":"Generates missing or changed blocks and joins them into one file (or a ZIP per chapter). The result has `file_id` and optional `subtitle_file_id`.","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"format":{"default":"mp3","type":"string","enum":["mp3","wav","flac"]},"per_chapter":{"default":false,"description":"One file per chapter (delivered as a ZIP)","type":"boolean"},"subtitles":{"default":false,"description":"Also produce an SRT subtitle file","type":"boolean"},"normalize":{"default":true,"description":"Loudness normalization (EBU R128, −16 LUFS)","type":"boolean"},"pause_ms":{"default":350,"description":"Silence between blocks","type":"integer","minimum":0,"maximum":5000},"chapter_pause_ms":{"default":1500,"type":"integer","minimum":0,"maximum":10000},"chapter_ids":{"description":"Export only these chapters","minItems":1,"maxItems":500,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([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)$"}},"background_music_file_id":{"description":"Audio file mixed under the speech","type":"string","format":"uuid","pattern":"^([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)$"},"background_music_level":{"type":"number","minimum":0.05,"maximum":1},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/tts-projects/{project_id}/exports":{"get":{"operationId":"listTtsProjectExports","tags":["Text to speech projects"],"summary":"List a project's exports","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"job_id":{"type":["string","null"]},"format":{"type":"string"},"per_chapter":{"type":"boolean"},"file_id":{"type":["string","null"]},"subtitle_file_id":{"type":["string","null"]},"duration_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"created_at":{"type":"string"}},"required":["id","job_id","format","per_chapter","file_id","subtitle_file_id","duration_ms","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/transcriptions":{"post":{"operationId":"createTranscription","tags":["Transcription"],"summary":"Transcribe audio or video","description":"Starts a job that transcribes a file (`file_id`) or a public link (`url`). Credits are held for the file's duration (for links, the plan's maximum; the difference is released). The result has `transcription_id`; read it with `GET /v2/transcriptions/{id}`. The transcription also appears in the studio.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file_id":{"description":"Audio or video file from `POST /v2/files` (or `POST /v2/files/import`)","type":"string","format":"uuid","pattern":"^([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)$"},"url":{"description":"Public link to transcribe directly (direct file, YouTube, social media). The media is not kept","type":"string","maxLength":2000,"format":"uri"},"name":{"type":"string","minLength":1,"maxLength":200},"language":{"default":"auto","description":"Spoken language, or `auto` to detect","anyOf":[{"type":"string","const":"auto"},{"type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$","description":"Language code, BCP-47 or base (e.g. `tr`, `en-US`, `pt-BR`)"}]},"speaker_labels":{"default":true,"description":"Detect and label speakers","type":"boolean"},"vocabulary":{"default":[],"description":"Custom terms for this transcription (names, jargon). Paid plans; at most 100 together with the account vocabulary","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":60}},"use_account_vocabulary":{"default":true,"description":"Also apply the account's vocabulary managed in the studio","type":"boolean"},"remove_fillers":{"default":false,"description":"Remove filler words (uh, um, hmm…)","type":"boolean"},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}]},"get":{"operationId":"listTranscriptions","tags":["Transcription"],"summary":"List transcriptions","description":"Newest first. Failed transcriptions are listed with status `failed`.","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["processing","completed","failed"]}},{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":100},"description":"Search in names and text"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"transcription"},"name":{"type":"string"},"status":{"type":"string","enum":["processing","completed","failed"]},"language":{"description":"Detected or given language","type":["string","null"]},"requested_language":{"type":["string","null"]},"duration_ms":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source_type":{"type":"string","enum":["file","recording","url"]},"source_file_id":{"type":["string","null"]},"source_url":{"type":["string","null"]},"speakers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"description":"Name given in the studio; null = unnamed (Speaker N)","type":["string","null"]},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","name","index"],"additionalProperties":false}},"job_id":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","status","language","requested_language","duration_ms","source_type","source_file_id","source_url","speakers","job_id","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/transcriptions/{transcription_id}":{"get":{"operationId":"getTranscription","tags":["Transcription"],"summary":"Get a transcription","description":"Segments with speakers and timings, plus the summary, action items and chapters if they were generated.","parameters":[{"name":"transcription_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"words","in":"query","required":false,"schema":{"default":"true","type":"string","enum":["true","false"]},"description":"Include word-level timings in segments"},{"name":"translation","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$"},"description":"Also return the translation into this language per segment (`translation` field); it must exist (see `POST /v2/transcriptions/{id}/translate`)"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"transcription"},"name":{"type":"string"},"status":{"type":"string","enum":["processing","completed","failed"]},"language":{"description":"Detected or given language","type":["string","null"]},"requested_language":{"type":["string","null"]},"duration_ms":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"source_type":{"type":"string","enum":["file","recording","url"]},"source_file_id":{"type":["string","null"]},"source_url":{"type":["string","null"]},"speakers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"description":"Name given in the studio; null = unnamed (Speaker N)","type":["string","null"]},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","name","index"],"additionalProperties":false}},"job_id":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_format":{"description":"Format of the source media (e.g. `MP3`, `MP4`)","type":["string","null"]},"options":{"type":"object","properties":{"speaker_labels":{"type":["boolean","null"]},"remove_fillers":{"type":["boolean","null"]},"vocabulary_terms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["speaker_labels","remove_fillers","vocabulary_terms"],"additionalProperties":false},"error_code":{"description":"Why the transcription failed (status `failed`)","type":["string","null"]},"summary":{"anyOf":[{"type":"object","properties":{"title":{"type":["string","null"]},"summary":{"type":["string","null"]},"key_points":{"type":"array","items":{"type":"string"}},"action_items":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"owner":{"type":["string","null"]}},"required":["text","owner"],"additionalProperties":false}},"job_id":{"type":["string","null"]},"created_at":{"type":["string","null"]}},"required":["title","summary","key_points","action_items","job_id","created_at"],"additionalProperties":false},{"type":"null"}],"description":"From `POST /v2/transcriptions/{id}/summary`"},"action_items":{"anyOf":[{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"owner":{"type":["string","null"]},"due":{"type":["string","null"]}},"required":["text","owner","due"],"additionalProperties":false}},"job_id":{"type":["string","null"]},"created_at":{"type":["string","null"]}},"required":["items","job_id","created_at"],"additionalProperties":false},{"type":"null"}],"description":"From `POST /v2/transcriptions/{id}/action-items`"},"chapters":{"anyOf":[{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"start_ms":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"title":{"type":"string"}},"required":["start_ms","title"],"additionalProperties":false}},"job_id":{"type":["string","null"]},"created_at":{"type":["string","null"]}},"required":["items","job_id","created_at"],"additionalProperties":false},{"type":"null"}],"description":"From `POST /v2/transcriptions/{id}/chapters`"},"translations":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"updated_at":{"type":"string"}},"required":["language","updated_at"],"additionalProperties":false}},"segments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"start_ms":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"end_ms":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker":{"description":"Speaker id (see `speakers`)","type":["string","null"]},"text":{"type":"string"},"confidence":{"type":["number","null"]},"words":{"type":"array","items":{"type":"object","properties":{"start_ms":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"end_ms":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"text":{"type":"string"},"confidence":{"type":["number","null"]}},"required":["start_ms","end_ms","text","confidence"],"additionalProperties":false}},"translation":{"type":["string","null"]}},"required":["id","index","start_ms","end_ms","speaker","text","confidence"],"additionalProperties":false}}},"required":["id","object","name","status","language","requested_language","duration_ms","source_type","source_file_id","source_url","speakers","job_id","created_at","updated_at","source_format","options","error_code","summary","action_items","chapters","translations","segments"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/transcriptions/{transcription_id}/export":{"get":{"operationId":"exportTranscription","tags":["Transcription"],"summary":"Export a transcription","description":"Returns the file itself (not JSON) with `Content-Disposition: attachment`: plain text, Word, PDF, SRT/VTT subtitles, Excel, JSON, CSV or ELAN. Pass `language` to export a translation. Free.","parameters":[{"name":"transcription_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","required":true,"schema":{"type":"string","enum":["txt","docx","pdf","srt","vtt","xlsx","json","csv","elan"]},"description":"`elan` produces an ELAN `.eaf` file"},{"name":"language","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$"},"description":"Export a translation in this language (timings come from the original)"},{"name":"timestamps","in":"query","required":false,"schema":{"default":"short","type":"string","enum":["none","short","full"]},"description":"Text formats: `short` = [1:02], `full` = [00:01:02.345 --> …]; documents: any value other than `none` shows timestamps"},{"name":"speakers","in":"query","required":false,"schema":{"default":"true","type":"string","enum":["true","false"]},"description":"Include speaker names"},{"name":"paragraphs","in":"query","required":false,"schema":{"default":"false","type":"string","enum":["true","false"]},"description":"Merge consecutive segments of the same speaker"},{"name":"max_chars_per_line","in":"query","required":false,"schema":{"default":42,"type":"integer","minimum":20,"maximum":80},"description":"Subtitles (`srt`, `vtt`): characters per line"},{"name":"max_lines","in":"query","required":false,"schema":{"default":2,"type":"integer","minimum":1,"maximum":3},"description":"Subtitles (`srt`, `vtt`): lines per cue"}],"responses":{"200":{"description":"Success"},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/transcriptions/{transcription_id}/translate":{"post":{"operationId":"translateTranscription","tags":["Transcription"],"summary":"Translate a transcription","description":"Starts a job that translates every segment into `target_language` (timings are kept). Read it with `GET /v2/transcriptions/{id}?translation=` or export it with `language`. Translating again into the same language replaces the previous translation.","parameters":[{"name":"transcription_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target_language":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$","description":"Language code, BCP-47 or base (e.g. `tr`, `en-US`, `pt-BR`)"},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"required":["target_language"],"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/transcriptions/{transcription_id}/summary":{"post":{"operationId":"summarizeTranscription","tags":["Transcription"],"summary":"Summarize a transcription","description":"Starts a job that writes a title, summary, key points and action items. The result has `summary`; it is also stored on the transcription (`summary`).","parameters":[{"name":"transcription_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/transcriptions/{transcription_id}/action-items":{"post":{"operationId":"extractTranscriptionActionItems","tags":["Transcription"],"summary":"Extract action items","description":"Starts a job that lists tasks with owners and due dates mentioned in the recording. The result has `action_items`; they are also stored on the transcription.","parameters":[{"name":"transcription_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/transcriptions/{transcription_id}/chapters":{"post":{"operationId":"chapterTranscription","tags":["Transcription"],"summary":"Split a transcription into chapters","description":"Starts a job that splits the recording into topics with start times and titles. The result has `chapters`; they are also stored on the transcription.","parameters":[{"name":"transcription_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/transcriptions/{transcription_id}/ask":{"post":{"operationId":"askTranscription","tags":["Transcription"],"summary":"Ask a question about a transcription","description":"Starts a job that answers a question from the transcription's content. Earlier questions on the same transcription are used as context. The result has `question` and `answer`.","parameters":[{"name":"transcription_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","minLength":1,"maxLength":2000},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"required":["question"],"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/dubbing":{"post":{"operationId":"createDubbing","tags":["Dubbing"],"summary":"Dub a video or audio file","description":"Creates a dubbing (it also appears in the studio) and starts a job that transcribes, translates and re-voices the source into every target language. The response is the job plus the new `dubbing`; poll `GET /v2/jobs/{id}` or `GET /v2/dubbing/{id}`, or pass `webhook_url`. Download results with `GET /v2/dubbing/{id}/languages/{language}/outputs`. Give the source as `file_id` (upload with `POST /v2/files`) or `source_url`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"file_id":{"description":"Audio or video file from `POST /v2/files` (status `ready`)","type":"string","format":"uuid","pattern":"^([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)$"},"source_url":{"description":"Public link to the media (direct file, YouTube, social media). Use instead of `file_id`","type":"string","maxLength":2000,"format":"uri"},"transcript_file_id":{"description":"Timed transcript of the source (SRT, VTT, transcription JSON …) uploaded with `POST /v2/files`. Transcription is skipped and not charged","type":"string","format":"uuid","pattern":"^([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)$"},"source_language":{"description":"Language spoken in the source; detected automatically when omitted","type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$"},"target_languages":{"description":"Languages to dub into","minItems":1,"maxItems":10,"type":"array","items":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$","description":"BCP-47 language code (e.g. `en-US`, `es-ES`, `de-DE`)"}},"mode":{"default":"fast","description":"`fast`: up to 60 min; `studio`: higher quality, voice matching, up to 120 min (plan feature)","type":"string","enum":["fast","studio"]},"options":{"type":"object","properties":{"original_audio":{"description":"`duck` (default): the original speech stays quietly under the dub; `mute`: it is muted while the dub speaks","type":"string","enum":["duck","mute"]},"vocal_separation":{"description":"Separate the voice from background music for a cleaner mix (`studio` mode only)","type":"boolean"},"subtitles":{"description":"`files` (default): SRT and VTT files; `burned_in`: files plus target subtitles burned into the video; `none`","type":"string","enum":["none","files","burned_in"]},"stems":{"description":"Also deliver separate speech and background tracks","type":"boolean"},"style":{"description":"Translation style (default `natural`)","type":"string","enum":["natural","formal","casual"]}},"additionalProperties":false,"description":"Dubbing options"},"max_duration_seconds":{"description":"Only with `source_url`: longest duration accepted (credits are held for this length; the real length is charged)","type":"integer","minimum":10,"maximum":14400},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"required":["name"],"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"dubbing":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"dubbing"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","processing","ready","partial","failed"],"description":"`partial`: some languages are ready, others failed"},"source":{"type":"object","properties":{"file_id":{"type":["string","null"]},"url":{"type":["string","null"]},"duration_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"is_video":{"type":["boolean","null"]}},"required":["file_id","url","duration_ms","is_video"],"additionalProperties":false},"transcript_file_id":{"type":["string","null"]},"source_language":{"type":["string","null"]},"detected_language":{"type":["string","null"]},"mode":{"type":"string","enum":["fast","studio"]},"options":{"type":"object","properties":{"original_audio":{"type":"string","enum":["duck","mute"]},"vocal_separation":{"type":"boolean"},"subtitles":{"type":"string","enum":["none","files","burned_in"]},"stems":{"type":"boolean"},"style":{"type":"string","enum":["natural","formal","casual"]}},"required":["original_audio","vocal_separation","subtitles","stems","style"],"additionalProperties":false},"languages":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"status":{"type":"string","enum":["pending","processing","ready","failed","canceled"]},"error_code":{"type":["string","null"]},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases every time the language's outputs are regenerated"},"outputs":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Output type → file id (e.g. `video`, `audio`, `subtitles_srt`); download with `GET /v2/dubbing/{id}/languages/{language}/outputs`"}},"required":["language","status","error_code","version","outputs"],"additionalProperties":false}},"last_job":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"operation":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"error_code":{"type":["string","null"]}},"required":["id","operation","status","progress","error_code"],"additionalProperties":false},{"type":"null"}],"description":"Latest job that ran on this dubbing; full details at `GET /v2/jobs/{id}`"},"segment_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","status","source","transcript_file_id","source_language","detected_language","mode","options","languages","last_job","segment_count","speaker_count","created_at","updated_at"],"additionalProperties":false}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at","dubbing"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}]},"get":{"operationId":"listDubbings","tags":["Dubbing"],"summary":"List dubbings","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"dubbing"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","processing","ready","partial","failed"],"description":"`partial`: some languages are ready, others failed"},"source":{"type":"object","properties":{"file_id":{"type":["string","null"]},"url":{"type":["string","null"]},"duration_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"is_video":{"type":["boolean","null"]}},"required":["file_id","url","duration_ms","is_video"],"additionalProperties":false},"transcript_file_id":{"type":["string","null"]},"source_language":{"type":["string","null"]},"detected_language":{"type":["string","null"]},"mode":{"type":"string","enum":["fast","studio"]},"options":{"type":"object","properties":{"original_audio":{"type":"string","enum":["duck","mute"]},"vocal_separation":{"type":"boolean"},"subtitles":{"type":"string","enum":["none","files","burned_in"]},"stems":{"type":"boolean"},"style":{"type":"string","enum":["natural","formal","casual"]}},"required":["original_audio","vocal_separation","subtitles","stems","style"],"additionalProperties":false},"languages":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"status":{"type":"string","enum":["pending","processing","ready","failed","canceled"]},"error_code":{"type":["string","null"]},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases every time the language's outputs are regenerated"},"outputs":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Output type → file id (e.g. `video`, `audio`, `subtitles_srt`); download with `GET /v2/dubbing/{id}/languages/{language}/outputs`"}},"required":["language","status","error_code","version","outputs"],"additionalProperties":false}},"last_job":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"operation":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"error_code":{"type":["string","null"]}},"required":["id","operation","status","progress","error_code"],"additionalProperties":false},{"type":"null"}],"description":"Latest job that ran on this dubbing; full details at `GET /v2/jobs/{id}`"},"segment_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","status","source","transcript_file_id","source_language","detected_language","mode","options","languages","last_job","segment_count","speaker_count","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/dubbing/voices":{"get":{"operationId":"listDubbingVoices","tags":["Dubbing"],"summary":"List voices available for dubbing","description":"Library voices that can speak the given language, plus your usable voice clones (listed first).","parameters":[{"name":"language","in":"query","required":true,"schema":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$"},"description":"Target language"},{"name":"gender","in":"query","required":false,"schema":{"type":"string","enum":["male","female","neutral"]}},{"name":"expressive","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"Only expressive voices (supports emotion and direction); voice clones are not included"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Voice id (`voice_…` or `clone_…`)"},"name":{"type":"string"},"description":{"type":["string","null"]},"source":{"type":"string","enum":["library","clone"]},"languages":{"type":"array","items":{"type":"string"}},"multilingual":{"type":"boolean"},"accent":{"type":["string","null"]},"gender":{"type":["string","null"]},"quality":{"type":"string","enum":["standard","premium"]},"styles":{"type":"array","items":{"type":"string"}},"expressive":{"type":"boolean"}},"required":["id","name","description","source","languages","multilingual","accent","gender","quality","styles","expressive"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/dubbing/{dubbing_id}":{"get":{"operationId":"getDubbing","tags":["Dubbing"],"summary":"Get a dubbing","parameters":[{"name":"dubbing_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"dubbing"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","processing","ready","partial","failed"],"description":"`partial`: some languages are ready, others failed"},"source":{"type":"object","properties":{"file_id":{"type":["string","null"]},"url":{"type":["string","null"]},"duration_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"is_video":{"type":["boolean","null"]}},"required":["file_id","url","duration_ms","is_video"],"additionalProperties":false},"transcript_file_id":{"type":["string","null"]},"source_language":{"type":["string","null"]},"detected_language":{"type":["string","null"]},"mode":{"type":"string","enum":["fast","studio"]},"options":{"type":"object","properties":{"original_audio":{"type":"string","enum":["duck","mute"]},"vocal_separation":{"type":"boolean"},"subtitles":{"type":"string","enum":["none","files","burned_in"]},"stems":{"type":"boolean"},"style":{"type":"string","enum":["natural","formal","casual"]}},"required":["original_audio","vocal_separation","subtitles","stems","style"],"additionalProperties":false},"languages":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"status":{"type":"string","enum":["pending","processing","ready","failed","canceled"]},"error_code":{"type":["string","null"]},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Increases every time the language's outputs are regenerated"},"outputs":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Output type → file id (e.g. `video`, `audio`, `subtitles_srt`); download with `GET /v2/dubbing/{id}/languages/{language}/outputs`"}},"required":["language","status","error_code","version","outputs"],"additionalProperties":false}},"last_job":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"operation":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"error_code":{"type":["string","null"]}},"required":["id","operation","status","progress","error_code"],"additionalProperties":false},{"type":"null"}],"description":"Latest job that ran on this dubbing; full details at `GET /v2/jobs/{id}`"},"segment_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"speaker_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","status","source","transcript_file_id","source_language","detected_language","mode","options","languages","last_job","segment_count","speaker_count","created_at","updated_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/dubbing/{dubbing_id}/languages":{"post":{"operationId":"addDubbingLanguage","tags":["Dubbing"],"summary":"Add a target language","description":"Starts a job that translates and re-voices an existing dubbing into one more language (the source is not transcribed again). The dubbing must have finished transcription and must not have a running job. Also retries a language that failed.","parameters":[{"name":"dubbing_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$","description":"BCP-47 language code (e.g. `en-US`, `es-ES`, `de-DE`)"},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"required":["language"],"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/dubbing/{dubbing_id}/languages/{language}/outputs":{"get":{"operationId":"listDubbingOutputs","tags":["Dubbing"],"summary":"Get download links for a language","description":"Output files of one target language with signed download URLs (valid for 15 minutes; call again for fresh links).","parameters":[{"name":"dubbing_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"language","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["video","audio","subtitles_srt","subtitles_vtt","source_subtitles_srt","speech_track","background_track"]},"file_id":{"type":"string"},"kind":{"type":"string"},"mime":{"type":"string"},"bytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"duration_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"name":{"type":["string","null"]},"download_url":{"type":"string"},"download_expires_at":{"type":"string"}},"required":["type","file_id","kind","mime","bytes","duration_ms","name","download_url","download_expires_at"],"additionalProperties":false}}},"required":["language","version","data"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/voice-clones/consent-sentence":{"post":{"operationId":"createVoiceCloneConsentSentence","tags":["Voice cloning"],"summary":"Get a consent sentence","description":"Step 1 of cloning. Returns a single-use sentence with random verification words (valid for 30 minutes) and the consent text. The voice owner reads the sentence aloud; upload that recording with `POST /v2/files` and pass it as `consent.recording_file_id` to `POST /v2/voice-clones`. The clone job checks that the recording really contains the sentence.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"description":"Language of the sentence and consent text (Turkish and English; others fall back to English). Defaults to the user's language","type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$"}},"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"consent_sentence"},"language":{"type":"string"},"sentence":{"type":"string","description":"Read this aloud, word for word"},"consent":{"type":"object","properties":{"version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"language":{"type":"string"},"text":{"type":"string"}},"required":["version","language","text"],"additionalProperties":false,"description":"Consent text you accept with `consent.accepted`"},"expires_at":{"type":"string"}},"required":["id","object","language","sentence","consent","expires_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}]}},"/v2/voice-clones":{"post":{"operationId":"createVoiceClone","tags":["Voice cloning"],"summary":"Create a voice clone","description":"Step 2 of cloning (paid plans). Records the consent and starts a job that verifies the consent recording, creates the voice and renders a short preview. The response is the job plus the new `voice_clone`. When the job succeeds the clone's `voice_id` works in `POST /v2/text-to-speech`, dubbing and the studio. If the consent recording does not contain the sentence the job fails and the clone gets `error_code` `consent_verification_failed`. Failed clones still count toward your clone limit until deleted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"description":{"type":"string","maxLength":300},"languages":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$","description":"BCP-47 language code (e.g. `tr-TR`, `en-US`)"},"description":"Languages the voice will speak"},"gender":{"type":"string","enum":["male","female","neutral"]},"sample_file_ids":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([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)$"},"description":"Audio or video recordings of the voice from `POST /v2/files` (status `ready`); 10 s to 5 min in total"},"share_with_team":{"default":false,"description":"Team accounts: other members can use the voice","type":"boolean"},"consent":{"type":"object","properties":{"sentence_id":{"type":"string","format":"uuid","pattern":"^([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)$","description":"`id` from `POST /v2/voice-clones/consent-sentence` (single use, valid for 30 minutes)"},"recording_file_id":{"type":"string","format":"uuid","pattern":"^([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)$","description":"Recording of the voice owner reading the consent sentence aloud (2–60 s; not one of the samples)"},"subject":{"type":"string","enum":["self","authorized"],"description":"`self`: it is your own voice; `authorized`: you have the owner's written permission"},"accepted":{"type":"boolean","const":true,"description":"You accept the consent text returned with the sentence"},"adult_declaration":{"type":"boolean","const":true,"description":"The voice does not belong to a person under 18"}},"required":["sentence_id","recording_file_id","subject","accepted","adult_declaration"],"additionalProperties":false,"description":"Verified consent of the voice owner"},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"required":["name","languages","sample_file_ids","consent"],"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"voice_clone":{"type":"object","properties":{"id":{"type":"string","description":"Voice clone id"},"object":{"type":"string","const":"voice_clone"},"voice_id":{"type":"string","description":"Use as `voice_id` in `POST /v2/text-to-speech` (and in the studio)"},"name":{"type":"string"},"description":{"type":["string","null"]},"languages":{"type":"array","items":{"type":"string"}},"gender":{"type":["string","null"]},"status":{"type":"string","enum":["processing","ready","failed"]},"usable":{"type":"boolean","description":"Ready and its consent is in place"},"consent_active":{"type":"boolean","description":"False after consent was withdrawn; the voice can no longer be used"},"error_code":{"type":["string","null"]},"job_id":{"description":"Job that created the clone","type":["string","null"]},"has_preview":{"type":"boolean"},"shared_with_team":{"type":"boolean"},"created_by_you":{"type":"boolean","description":"Created by the user the API key belongs to"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","voice_id","name","description","languages","gender","status","usable","consent_active","error_code","job_id","has_preview","shared_with_team","created_by_you","created_at","updated_at"],"additionalProperties":false}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at","voice_clone"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}]},"get":{"operationId":"listVoiceClones","tags":["Voice cloning"],"summary":"List voice clones","description":"Voice clones of the account you can see (yours, and those shared with the team).","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["processing","ready","failed"]}},{"name":"usable","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"`true`: only voices that can be used now"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Voice clone id"},"object":{"type":"string","const":"voice_clone"},"voice_id":{"type":"string","description":"Use as `voice_id` in `POST /v2/text-to-speech` (and in the studio)"},"name":{"type":"string"},"description":{"type":["string","null"]},"languages":{"type":"array","items":{"type":"string"}},"gender":{"type":["string","null"]},"status":{"type":"string","enum":["processing","ready","failed"]},"usable":{"type":"boolean","description":"Ready and its consent is in place"},"consent_active":{"type":"boolean","description":"False after consent was withdrawn; the voice can no longer be used"},"error_code":{"type":["string","null"]},"job_id":{"description":"Job that created the clone","type":["string","null"]},"has_preview":{"type":"boolean"},"shared_with_team":{"type":"boolean"},"created_by_you":{"type":"boolean","description":"Created by the user the API key belongs to"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","voice_id","name","description","languages","gender","status","usable","consent_active","error_code","job_id","has_preview","shared_with_team","created_by_you","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/voice-clones/{voice_clone_id}":{"get":{"operationId":"getVoiceClone","tags":["Voice cloning"],"summary":"Get a voice clone","description":"Accepts the clone id or its `voice_id` (`clone_…`).","parameters":[{"name":"voice_clone_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Voice clone id"},"object":{"type":"string","const":"voice_clone"},"voice_id":{"type":"string","description":"Use as `voice_id` in `POST /v2/text-to-speech` (and in the studio)"},"name":{"type":"string"},"description":{"type":["string","null"]},"languages":{"type":"array","items":{"type":"string"}},"gender":{"type":["string","null"]},"status":{"type":"string","enum":["processing","ready","failed"]},"usable":{"type":"boolean","description":"Ready and its consent is in place"},"consent_active":{"type":"boolean","description":"False after consent was withdrawn; the voice can no longer be used"},"error_code":{"type":["string","null"]},"job_id":{"description":"Job that created the clone","type":["string","null"]},"has_preview":{"type":"boolean"},"shared_with_team":{"type":"boolean"},"created_by_you":{"type":"boolean","description":"Created by the user the API key belongs to"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preview_url":{"description":"Signed URL of a short sample in the cloned voice (valid for 15 minutes)","type":["string","null"]},"preview_expires_at":{"type":["string","null"]}},"required":["id","object","voice_id","name","description","languages","gender","status","usable","consent_active","error_code","job_id","has_preview","shared_with_team","created_by_you","created_at","updated_at","preview_url","preview_expires_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteVoiceClone","tags":["Voice cloning"],"summary":"Delete a voice clone","description":"Permanently deletes the voice, its consent recording and preview. This cannot be undone. Your original sample files are kept. Only the creator or an account admin can delete; a clone whose creation job is still running cannot be deleted.","parameters":[{"name":"voice_clone_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"voice_clone"},"deleted":{"type":"boolean","const":true}},"required":["id","object","deleted"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/voice-clones/{voice_clone_id}/speech":{"post":{"operationId":"createVoiceCloneSpeech","tags":["Voice cloning"],"summary":"Speak short text with a voice clone","description":"Starts a job that speaks short text with the clone. The voice must be ready and its consent in place. The result has `file_id`.","parameters":[{"name":"voice_clone_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1000,"description":"Text to speak (up to 1000 characters; use `POST /v2/text-to-speech` with the clone's `voice_id` for longer text)"},"language":{"description":"Language of the text; defaults to the voice's first language","type":"string","pattern":"^[a-z]{2,3}(-[A-Za-z0-9]{2,8}){0,2}$"},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"required":["text"],"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/music/catalog":{"get":{"operationId":"getMusicCatalog","tags":["Music"],"summary":"Get the music catalog","description":"Genres, moods, tempos, vocals, song languages, lengths and lyric actions accepted by `POST /v2/music` and `POST /v2/music/lyrics`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"genres":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"family":{"type":"string"},"languages":{"type":"array","items":{"type":"string"},"description":"Languages the genre is typical for; empty = any"}},"required":["id","family","languages"],"additionalProperties":false}},"genre_families":{"type":"array","items":{"type":"string"}},"max_genres":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"moods":{"type":"array","items":{"type":"string"}},"tempos":{"type":"array","items":{"type":"string"}},"vocals":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"lengths":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["short","full"]},"seconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Approximate; null = about 2–3 minutes"}},"required":["id","seconds"],"additionalProperties":false}},"lyric_actions":{"type":"array","items":{"type":"string"}},"formats":{"type":"object","properties":{"mp3":{"type":"boolean"},"wav":{"type":"boolean"},"stems":{"type":"boolean"}},"required":["mp3","wav","stems"],"additionalProperties":false},"limits":{"type":"object","properties":{"prompt":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lyrics":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"style":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["prompt","lyrics","style"],"additionalProperties":false},"license":{"type":"object","properties":{"free":{"type":"string","const":"personal"},"paid":{"type":"string","const":"commercial"}},"required":["free","paid"],"additionalProperties":false},"free_plan":{"type":"object","properties":{"length":{"type":"string","const":"short"},"versions":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"download":{"type":"boolean"}},"required":["length","versions","download"],"additionalProperties":false},"versions_per_generation":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Versions produced per generation on paid plans"}},"required":["genres","genre_families","max_genres","moods","tempos","vocals","languages","lengths","lyric_actions","formats","limits","license","free_plan","versions_per_generation"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/music":{"post":{"operationId":"createMusic","tags":["Music"],"summary":"Generate a song","description":"Creates a track (it also appears in the studio) and starts a job that generates it. Paid plans get two versions per generation, free plans one short version. The job result has `track_id`, `versions[].file_id` and `cover_file_id`; full details are at `GET /v2/music/{id}`. Downloading the MP3 requires a paid plan.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Track name; generated from the song when omitted","type":"string","minLength":1,"maxLength":80},"mode":{"default":"describe","description":"`describe`: write a song from `prompt` and/or `genres`. `lyrics`: sing the given `lyrics`","type":"string","enum":["describe","lyrics"]},"prompt":{"description":"What the song is about, its feel and instruments","type":"string","maxLength":500},"genres":{"default":[],"description":"Up to 3 genre ids; the first is the main genre","maxItems":3,"type":"array","items":{"type":"string","description":"Genre id from `GET /v2/music/catalog`"}},"mood":{"type":"string","enum":["happy","romantic","sad","energetic","chill","epic","nostalgic","funny","dreamy","dark","motivational","peaceful"]},"tempo":{"default":"auto","type":"string","enum":["auto","slow","medium","fast"]},"vocal":{"default":"auto","description":"`instrumental` = no vocals","type":"string","enum":["auto","female","male","duet","choir","instrumental"]},"language":{"default":"auto","type":"string","enum":["auto","tr","en","ar","de","es","fr","hi","it","ja","ko","nl","pl","pt","ru","sv","zh","id","ms","fa","ur","bn","az","uk","el","ro","th","vi"],"description":"Song language (`auto` = from the prompt or lyrics)"},"lyrics":{"description":"Lyrics to sing (required in `lyrics` mode). Section tags like `[Verse]`, `[Chorus]` are supported","type":"string","maxLength":3000},"style":{"description":"Extra free-form style direction","type":"string","maxLength":200},"length":{"default":"short","description":"`short` ≈ 30 seconds; `full` ≈ 2–3 minutes (paid plans)","type":"string","enum":["short","full"]},"folder":{"description":"Studio folder name","type":"string","minLength":1,"maxLength":60},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}]},"get":{"operationId":"listMusic","tags":["Music"],"summary":"List tracks","description":"Tracks with at least one generation, newest first (shared with the studio).","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}},{"name":"folder","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":60}},{"name":"favorite","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"music_track"},"name":{"type":"string"},"folder":{"type":["string","null"]},"mode":{"type":"string"},"prompt":{"type":["string","null"]},"genres":{"type":"array","items":{"type":"string"}},"mood":{"type":["string","null"]},"tempo":{"type":"string"},"vocal":{"type":"string"},"language":{"type":"string"},"lyrics":{"type":["string","null"]},"style":{"type":["string","null"]},"length":{"type":"string","enum":["short","full"]},"license":{"anyOf":[{"type":"string","enum":["personal","commercial"]},{"type":"null"}],"description":"Usage license of the generated versions"},"favorite":{"type":"boolean"},"cover_file_id":{"type":["string","null"]},"status":{"type":"string","enum":["draft","queued","running","succeeded","failed","canceled"],"description":"Status of the latest generation"},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"job_id":{"description":"Latest generation job","type":["string","null"]},"error_code":{"type":["string","null"]},"versions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"job_id":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"0 = version A, 1 = version B"},"file_id":{"type":"string","description":"MP3 file; get a download URL from `GET /v2/files/{id}` (paid plans)"},"duration_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"lyrics":{"description":"Lyrics as sung","type":["string","null"]},"sections":{"type":"array","items":{"type":"object","properties":{"type":{"type":["string","null"]},"lines":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"start_seconds":{"type":["number","null"]},"end_seconds":{"type":["number","null"]}},"required":["text","start_seconds","end_seconds"],"additionalProperties":false}}},"required":["type","lines"],"additionalProperties":false}},"created_at":{"type":"string"}},"required":["id","job_id","index","file_id","duration_ms","lyrics","sections","created_at"],"additionalProperties":false},"description":"Generated versions, newest generation first"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","folder","mode","prompt","genres","mood","tempo","vocal","language","lyrics","style","length","license","favorite","cover_file_id","status","progress","job_id","error_code","versions","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/music/{track_id}":{"get":{"operationId":"getMusic","tags":["Music"],"summary":"Get a track","description":"Settings, status of the latest generation and all generated versions with their `file_id`.","parameters":[{"name":"track_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"music_track"},"name":{"type":"string"},"folder":{"type":["string","null"]},"mode":{"type":"string"},"prompt":{"type":["string","null"]},"genres":{"type":"array","items":{"type":"string"}},"mood":{"type":["string","null"]},"tempo":{"type":"string"},"vocal":{"type":"string"},"language":{"type":"string"},"lyrics":{"type":["string","null"]},"style":{"type":["string","null"]},"length":{"type":"string","enum":["short","full"]},"license":{"anyOf":[{"type":"string","enum":["personal","commercial"]},{"type":"null"}],"description":"Usage license of the generated versions"},"favorite":{"type":"boolean"},"cover_file_id":{"type":["string","null"]},"status":{"type":"string","enum":["draft","queued","running","succeeded","failed","canceled"],"description":"Status of the latest generation"},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"job_id":{"description":"Latest generation job","type":["string","null"]},"error_code":{"type":["string","null"]},"versions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"job_id":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"0 = version A, 1 = version B"},"file_id":{"type":"string","description":"MP3 file; get a download URL from `GET /v2/files/{id}` (paid plans)"},"duration_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"lyrics":{"description":"Lyrics as sung","type":["string","null"]},"sections":{"type":"array","items":{"type":"object","properties":{"type":{"type":["string","null"]},"lines":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"start_seconds":{"type":["number","null"]},"end_seconds":{"type":["number","null"]}},"required":["text","start_seconds","end_seconds"],"additionalProperties":false}}},"required":["type","lines"],"additionalProperties":false}},"created_at":{"type":"string"}},"required":["id","job_id","index","file_id","duration_ms","lyrics","sections","created_at"],"additionalProperties":false},"description":"Generated versions, newest generation first"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","object","name","folder","mode","prompt","genres","mood","tempo","vocal","language","lyrics","style","length","license","favorite","cover_file_id","status","progress","job_id","error_code","versions","created_at","updated_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/music/lyrics":{"post":{"operationId":"createLyrics","tags":["Music"],"summary":"Write or rework song lyrics","description":"Starts a job that writes lyrics from a topic, or continues, rhymes, shortens, adds a chorus to, translates or structures existing lyrics. The result has `title`, `language`, `lyrics` and `sections`; pass `lyrics` to `POST /v2/music` with `mode: \"lyrics\"`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"default":"write","description":"`write` new lyrics from `topic`; the others rework the given `lyrics`","type":"string","enum":["write","continue","rhyme","shorten","chorus","translate","structure"]},"topic":{"description":"What the song is about (required for `write`)","type":"string","maxLength":500},"lyrics":{"description":"Existing lyrics to rework (required for every action except `write`)","type":"string","maxLength":3000},"language":{"default":"auto","type":"string","enum":["auto","tr","en","ar","de","es","fr","hi","it","ja","ko","nl","pl","pt","ru","sv","zh","id","ms","fa","ur","bn","az","uk","el","ro","th","vi"],"description":"Song language (`auto` = from the prompt or lyrics)"},"target_language":{"description":"Required for `translate`","type":"string","enum":["auto","tr","en","ar","de","es","fr","hi","it","ja","ko","nl","pl","pt","ru","sv","zh","id","ms","fa","ur","bn","az","uk","el","ro","th","vi"]},"genre":{"type":"string","description":"Genre id from `GET /v2/music/catalog`"},"mood":{"type":"string","enum":["happy","romantic","sad","energetic","chill","epic","nostalgic","funny","dreamy","dark","motivational","peaceful"]},"length":{"default":"full","type":"string","enum":["short","full"]},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}]}},"/v2/video/catalog":{"get":{"operationId":"getVideoCatalog","tags":["Video"],"summary":"Get video options","description":"Qualities, modes, durations, aspect ratios, styles, camera moves and templates accepted by `POST /v2/videos`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"qualities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["economy","standard"]},"name":{"type":"string"},"description":{"type":"string"},"resolutions":{"type":"array","items":{"type":"string","enum":["720p","1080p","4k"]}},"supports_reference":{"type":"boolean"}},"required":["id","name","description","resolutions","supports_reference"],"additionalProperties":false}},"modes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["text","image","first_last_frame","reference"]},"name":{"type":"string"},"description":{"type":"string"}},"required":["id","name","description"],"additionalProperties":false}},"durations":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"Allowed `duration_seconds` values"},"aspect_ratios":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["16:9","9:16","1:1"]},"note":{"type":["string","null"]}},"required":["id","note"],"additionalProperties":false}},"styles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"camera_moves":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"max_camera_moves":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"variations":{"type":"object","properties":{"min":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["min","max"],"additionalProperties":false},"extend":{"type":"object","properties":{"seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max_total_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["seconds","max_total_seconds"],"additionalProperties":false},"templates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["effect","scene"],"description":"`effect` animates an uploaded photo; `scene` is a prompt template filled with your subject"},"mode":{"type":"string","enum":["text","image"]},"aspect_ratio":{"description":"Fixed aspect ratio, if any","type":["string","null"]},"duration_seconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Fixed duration, if any"},"subject_required":{"type":"boolean","description":"`prompt` is required (it is the template's subject)"}},"required":["id","name","type","mode","aspect_ratio","duration_seconds","subject_required"],"additionalProperties":false}},"free_plan":{"type":"object","properties":{"quality":{"type":"string"},"resolution":{"type":"string"},"max_variations":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"watermark":{"type":"boolean"}},"required":["quality","resolution","max_variations","watermark"],"additionalProperties":false}},"required":["qualities","modes","durations","aspect_ratios","styles","camera_moves","max_camera_moves","variations","extend","templates","free_plan"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/videos":{"post":{"operationId":"createVideo","tags":["Video"],"summary":"Generate a video","description":"Starts a job that generates a video from text, an image, a first and last frame, or reference images. Upload images first with `POST /v2/files`. Poll `GET /v2/jobs/{id}` or pass `webhook_url`; the result has `video_id` and `outputs` (one per variation). Videos on the free plan are watermarked.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"default":"text","description":"`image`: starts from `first_frame_file_id`; `first_last_frame`: also ends on `last_frame_file_id`; `reference`: keeps subjects consistent with `reference_file_ids`","type":"string","enum":["text","image","first_last_frame","reference"]},"prompt":{"default":"","description":"Scene description. Required for `text` and `reference` modes and for templates with `subject_required`","type":"string","maxLength":2000},"negative_prompt":{"description":"Things you don't want to see","type":"string","maxLength":500},"quality":{"default":"economy","description":"See `GET /v2/video/catalog`","type":"string","enum":["economy","standard"]},"duration_seconds":{"default":8,"anyOf":[{"type":"number","const":4},{"type":"number","const":6},{"type":"number","const":8}]},"resolution":{"default":"720p","description":"`4k` requires `standard` quality","type":"string","enum":["720p","1080p","4k"]},"aspect_ratio":{"default":"16:9","type":"string","enum":["16:9","9:16","1:1"]},"style":{"type":"string","enum":["cinematic","anime","3d","clay","realistic","vintage"]},"camera_moves":{"default":[],"maxItems":2,"type":"array","items":{"type":"string","enum":["zoom_in","zoom_out","drone","slow_motion","tracking","orbit","handheld","static"]}},"audio":{"default":true,"description":"Generate sound with the video","type":"boolean"},"seed":{"type":"integer","minimum":0,"maximum":2147483647},"variations":{"default":1,"description":"Number of videos to generate from the same input; each is charged","type":"integer","minimum":1,"maximum":4},"first_frame_file_id":{"description":"Image file (`POST /v2/files`, purpose `first_frame`)","type":"string","format":"uuid","pattern":"^([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)$"},"last_frame_file_id":{"description":"Image file (`POST /v2/files`, purpose `last_frame`); `first_last_frame` mode only","type":"string","format":"uuid","pattern":"^([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)$"},"reference_file_ids":{"default":[],"description":"1–3 image files (purpose `reference`); `reference` mode only","maxItems":3,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([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)$"}},"template_id":{"description":"Template from the catalog; its mode must match `mode`","type":"string","enum":["effect_old_photo","effect_smile","effect_hug","product_promotion","street_interview","nature_documentary"]},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}]},"get":{"operationId":"listVideos","tags":["Video"],"summary":"List videos","description":"Videos of the account, newest first (including ones made in the studio).","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}},{"name":"favorite","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"video"},"job_id":{"type":"string"},"type":{"type":"string","enum":["generation","extension","merge"]},"mode":{"anyOf":[{"type":"string","enum":["text","image","first_last_frame","reference"]},{"type":"null"}],"description":"Generation mode; null for extensions and merges"},"prompt":{"type":["string","null"]},"quality":{"anyOf":[{"type":"string","enum":["economy","fast","standard"]},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"total_duration_seconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Extensions: length of the whole chain"},"resolution":{"type":["string","null"]},"aspect_ratio":{"type":["string","null"]},"style":{"type":["string","null"]},"camera_moves":{"type":"array","items":{"type":"string"}},"audio":{"type":"boolean"},"seed":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"variations":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"template_id":{"type":["string","null"]},"inputs":{"type":"object","properties":{"first_frame_file_id":{"type":["string","null"]},"last_frame_file_id":{"type":["string","null"]},"reference_file_ids":{"type":"array","items":{"type":"string"}},"source_video_id":{"description":"Extensions: the video that was extended","type":["string","null"]},"source_output_index":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["first_frame_file_id","last_frame_file_id","reference_file_ids","source_video_id","source_output_index"],"additionalProperties":false},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"error_code":{"type":["string","null"]},"rejection_reason":{"description":"Why the content was rejected (e.g. `celebrity`, `copyright`, `policy`)","type":["string","null"]},"warning":{"description":"Moderation warning that did not block the video (e.g. `public_figure`)","type":["string","null"]},"outputs":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"file_id":{"type":"string","description":"Video file; get a download URL from `GET /v2/files/{id}`"},"poster_file_id":{"description":"JPEG poster frame","type":["string","null"]},"duration_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"watermarked":{"type":"boolean"}},"required":["index","file_id","poster_file_id","duration_ms","width","height","watermarked"],"additionalProperties":false}},"filtered_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Variations removed by the safety filter (their credits are refunded)"},"watermarked":{"type":"boolean"},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"free_trial":{"type":"boolean"}},"required":["estimated","charged","free_trial"],"additionalProperties":false},"favorite":{"type":"boolean"},"created_at":{"type":"string"}},"required":["id","object","job_id","type","mode","prompt","quality","duration_seconds","total_duration_seconds","resolution","aspect_ratio","style","camera_moves","audio","seed","variations","template_id","inputs","status","progress","error_code","rejection_reason","warning","outputs","filtered_count","watermarked","credits","favorite","created_at"],"additionalProperties":false}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/videos/quote":{"post":{"operationId":"quoteVideo","tags":["Video"],"summary":"Estimate credits for a video","description":"Same body as `POST /v2/videos` (without `webhook_url`). Nothing is charged.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"default":"text","description":"`image`: starts from `first_frame_file_id`; `first_last_frame`: also ends on `last_frame_file_id`; `reference`: keeps subjects consistent with `reference_file_ids`","type":"string","enum":["text","image","first_last_frame","reference"]},"prompt":{"default":"","description":"Scene description. Required for `text` and `reference` modes and for templates with `subject_required`","type":"string","maxLength":2000},"negative_prompt":{"description":"Things you don't want to see","type":"string","maxLength":500},"quality":{"default":"economy","description":"See `GET /v2/video/catalog`","type":"string","enum":["economy","standard"]},"duration_seconds":{"default":8,"anyOf":[{"type":"number","const":4},{"type":"number","const":6},{"type":"number","const":8}]},"resolution":{"default":"720p","description":"`4k` requires `standard` quality","type":"string","enum":["720p","1080p","4k"]},"aspect_ratio":{"default":"16:9","type":"string","enum":["16:9","9:16","1:1"]},"style":{"type":"string","enum":["cinematic","anime","3d","clay","realistic","vintage"]},"camera_moves":{"default":[],"maxItems":2,"type":"array","items":{"type":"string","enum":["zoom_in","zoom_out","drone","slow_motion","tracking","orbit","handheld","static"]}},"audio":{"default":true,"description":"Generate sound with the video","type":"boolean"},"seed":{"type":"integer","minimum":0,"maximum":2147483647},"variations":{"default":1,"description":"Number of videos to generate from the same input; each is charged","type":"integer","minimum":1,"maximum":4},"first_frame_file_id":{"description":"Image file (`POST /v2/files`, purpose `first_frame`)","type":"string","format":"uuid","pattern":"^([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)$"},"last_frame_file_id":{"description":"Image file (`POST /v2/files`, purpose `last_frame`); `first_last_frame` mode only","type":"string","format":"uuid","pattern":"^([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)$"},"reference_file_ids":{"default":[],"description":"1–3 image files (purpose `reference`); `reference` mode only","maxItems":3,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([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)$"}},"template_id":{"description":"Template from the catalog; its mode must match `mode`","type":"string","enum":["effect_old_photo","effect_smile","effect_hug","product_promotion","street_interview","nature_documentary"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Credits the job will hold (upper bound; unused credits are released)"},"affordable":{"type":"boolean"},"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"details":{"type":"object","properties":{"seconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Seconds of video per output"},"variations":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"quality":{"type":["string","null"]},"chain_seconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Extension only: total length of the video after this extension"},"free_trial":{"type":"boolean","description":"Covered by the plan's free trial (no credits held)"}},"required":["seconds","variations","quality","chain_seconds","free_trial"],"additionalProperties":false}},"required":["credits","affordable","balance","details"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/videos/{video_id}":{"get":{"operationId":"getVideo","tags":["Video"],"summary":"Get a video","parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"video"},"job_id":{"type":"string"},"type":{"type":"string","enum":["generation","extension","merge"]},"mode":{"anyOf":[{"type":"string","enum":["text","image","first_last_frame","reference"]},{"type":"null"}],"description":"Generation mode; null for extensions and merges"},"prompt":{"type":["string","null"]},"quality":{"anyOf":[{"type":"string","enum":["economy","fast","standard"]},{"type":"null"}]},"duration_seconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"total_duration_seconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Extensions: length of the whole chain"},"resolution":{"type":["string","null"]},"aspect_ratio":{"type":["string","null"]},"style":{"type":["string","null"]},"camera_moves":{"type":"array","items":{"type":"string"}},"audio":{"type":"boolean"},"seed":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"variations":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"template_id":{"type":["string","null"]},"inputs":{"type":"object","properties":{"first_frame_file_id":{"type":["string","null"]},"last_frame_file_id":{"type":["string","null"]},"reference_file_ids":{"type":"array","items":{"type":"string"}},"source_video_id":{"description":"Extensions: the video that was extended","type":["string","null"]},"source_output_index":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["first_frame_file_id","last_frame_file_id","reference_file_ids","source_video_id","source_output_index"],"additionalProperties":false},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"error_code":{"type":["string","null"]},"rejection_reason":{"description":"Why the content was rejected (e.g. `celebrity`, `copyright`, `policy`)","type":["string","null"]},"warning":{"description":"Moderation warning that did not block the video (e.g. `public_figure`)","type":["string","null"]},"outputs":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"file_id":{"type":"string","description":"Video file; get a download URL from `GET /v2/files/{id}`"},"poster_file_id":{"description":"JPEG poster frame","type":["string","null"]},"duration_ms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"watermarked":{"type":"boolean"}},"required":["index","file_id","poster_file_id","duration_ms","width","height","watermarked"],"additionalProperties":false}},"filtered_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Variations removed by the safety filter (their credits are refunded)"},"watermarked":{"type":"boolean"},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"free_trial":{"type":"boolean"}},"required":["estimated","charged","free_trial"],"additionalProperties":false},"favorite":{"type":"boolean"},"created_at":{"type":"string"}},"required":["id","object","job_id","type","mode","prompt","quality","duration_seconds","total_duration_seconds","resolution","aspect_ratio","style","camera_moves","audio","seed","variations","template_id","inputs","status","progress","error_code","rejection_reason","warning","outputs","filtered_count","watermarked","credits","favorite","created_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/videos/{video_id}/extend":{"post":{"operationId":"extendVideo","tags":["Video"],"summary":"Extend a video","description":"Continues a finished video by 7 seconds and creates a new video. A chain can be up to 29 seconds long. Square (1:1) videos and merges can't be extended; paid plans only. The result has `video_id`.","parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"output_index":{"default":0,"description":"Which output (variation) of the video to extend","type":"integer","minimum":0,"maximum":3},"prompt":{"default":"","description":"What happens next; empty continues the scene","type":"string","maxLength":2000},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/videos/{video_id}/extend/quote":{"post":{"operationId":"quoteVideoExtension","tags":["Video"],"summary":"Estimate credits for extending a video","parameters":[{"name":"video_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"output_index":{"default":0,"description":"Which output (variation) of the video to extend","type":"integer","minimum":0,"maximum":3},"prompt":{"default":"","description":"What happens next; empty continues the scene","type":"string","maxLength":2000}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Credits the job will hold (upper bound; unused credits are released)"},"affordable":{"type":"boolean"},"balance":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"details":{"type":"object","properties":{"seconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Seconds of video per output"},"variations":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"quality":{"type":["string","null"]},"chain_seconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Extension only: total length of the video after this extension"},"free_trial":{"type":"boolean","description":"Covered by the plan's free trial (no credits held)"}},"required":["seconds","variations","quality","chain_seconds","free_trial"],"additionalProperties":false}},"required":["credits","affordable","balance","details"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/videos/enhance-prompt":{"post":{"operationId":"enhanceVideoPrompt","tags":["Video"],"summary":"Improve a video prompt","description":"Starts a short job that enriches a prompt with scene, lighting and camera details. The result has `prompt`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":2000},"webhook_url":{"description":"Public https URL notified when the job finishes (see Webhooks)","type":"string","maxLength":2000}},"required":["prompt"],"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Job id"},"object":{"type":"string","const":"job"},"operation":{"type":"string","description":"Operation that created the job (e.g. `text_to_speech`)"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"progress":{"type":"integer","minimum":0,"maximum":100},"credits":{"type":"object","properties":{"estimated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"charged":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["estimated","charged"],"additionalProperties":false},"result":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"Operation-specific result; null until the job succeeds"},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","role","index"],"additionalProperties":false},"description":"Files produced by the job; get a download URL from `GET /v2/files/{id}`"},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","details"],"additionalProperties":false},{"type":"null"}]},"created_at":{"type":"string"},"started_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]}},"required":["id","object","operation","status","progress","credits","result","files","error","created_at","started_at","completed_at"],"additionalProperties":false}}}},"4XX":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"5XX":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the original job instead of creating a new one (8–100 chars).","schema":{"type":"string","minLength":8,"maxLength":100}}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Create API keys in the studio: Settings → API keys."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","details","request_id"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code","examples":["wallet_insufficient_credits"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true},"request_id":{"type":["string","null"],"description":"Quote this when contacting support"}}}}}}},"x-error-codes":[{"code":"validation_failed","status":400,"message":"Request validation failed"},{"code":"validation_unknown_field","status":400,"message":"Unknown field in request"},{"code":"validation_bad_cursor","status":400,"message":"Invalid pagination cursor"},{"code":"validation_payload_too_large","status":413,"message":"Request body is too large"},{"code":"validation_method_not_allowed","status":405,"message":"HTTP method is not allowed on this endpoint"},{"code":"validation_webhook_url","status":400,"message":"Webhook URL must be a public https address"},{"code":"auth_required","status":401,"message":"Authentication required"},{"code":"auth_forbidden","status":403,"message":"Not allowed"},{"code":"auth_api_key_invalid","status":401,"message":"Invalid API key"},{"code":"account_role_required","status":403,"message":"Your role does not allow this action"},{"code":"account_api_key_not_found","status":404,"message":"API key not found"},{"code":"account_api_key_limit","status":409,"message":"API key limit reached"},{"code":"wallet_insufficient_credits","status":402,"message":"Insufficient credits"},{"code":"wallet_hold_not_found","status":404,"message":"Hold not found"},{"code":"wallet_already_settled","status":409,"message":"Hold is already settled"},{"code":"wallet_invalid_amount","status":400,"message":"Amount must be a positive integer"},{"code":"wallet_rate_missing","status":500,"message":"Credit rate is not defined"},{"code":"wallet_ref_conflict","status":409,"message":"Reference is already used by another account"},{"code":"job_not_found","status":404,"message":"Job not found"},{"code":"job_studio_unknown","status":400,"message":"Unknown studio"},{"code":"job_kind_unknown","status":400,"message":"Unknown job kind for this studio"},{"code":"job_input_invalid","status":400,"message":"Job input is invalid"},{"code":"job_not_cancelable","status":409,"message":"Job can no longer be canceled"},{"code":"job_concurrency_limit","status":429,"message":"Too many jobs running at once"},{"code":"job_idempotency_conflict","status":409,"message":"Idempotency key was used with a different request"},{"code":"job_failed","status":500,"message":"Job failed"},{"code":"job_canceled","status":409,"message":"Job was canceled"},{"code":"job_studio_disabled","status":404,"message":"Studio is not enabled"},{"code":"job_still_running","status":409,"message":"Job is still running"},{"code":"job_stalled","status":500,"message":"Job stopped responding"},{"code":"job_url_not_allowed","status":400,"message":"This address cannot be accessed"},{"code":"asset_not_found","status":404,"message":"Asset not found"},{"code":"asset_too_large","status":413,"message":"File is larger than the limit"},{"code":"asset_too_long","status":400,"message":"Media is longer than the limit"},{"code":"asset_type_not_allowed","status":415,"message":"File type is not allowed"},{"code":"asset_type_mismatch","status":415,"message":"File content does not match the declared type"},{"code":"asset_upload_incomplete","status":409,"message":"Upload is not complete"},{"code":"asset_upload_expired","status":410,"message":"Upload session expired"},{"code":"asset_not_ready","status":409,"message":"Asset is not ready"},{"code":"asset_url_invalid","status":403,"message":"Signed address is invalid"},{"code":"asset_url_expired","status":403,"message":"Signed address expired"},{"code":"asset_range_invalid","status":416,"message":"Upload range is invalid"},{"code":"asset_in_use","status":409,"message":"Asset is used by a running job"},{"code":"asset_empty","status":400,"message":"File is empty"},{"code":"asset_corrupt","status":422,"message":"File is damaged or cannot be read"},{"code":"asset_no_audio_track","status":422,"message":"Media has no audio track"},{"code":"asset_silent","status":422,"message":"No speech was detected in the media"},{"code":"asset_too_short","status":422,"message":"Media is too short"},{"code":"job_url_unreachable","status":422,"message":"The link could not be read"},{"code":"job_image_too_large","status":413,"message":"Image is too large for this generation"},{"code":"quota_rate_limited","status":429,"message":"Too many requests"},{"code":"quota_guest_exceeded","status":429,"message":"Free usage limit reached; sign up to continue"},{"code":"quota_daily_exceeded","status":429,"message":"Daily limit reached"},{"code":"quota_monthly_exceeded","status":429,"message":"Monthly limit reached"},{"code":"quota_verification_required","status":403,"message":"Human verification required"},{"code":"quota_verification_failed","status":403,"message":"Human verification failed"},{"code":"quota_guest_not_allowed","status":403,"message":"Sign in to use this feature"},{"code":"quota_storage_exceeded","status":413,"message":"Storage limit reached"},{"code":"provider_rejected","status":422,"message":"Provider rejected the content"},{"code":"provider_unavailable","status":503,"message":"Provider is unavailable"},{"code":"provider_clone_unavailable","status":503,"message":"Cloned voice cannot be synthesized right now"},{"code":"provider_timeout","status":504,"message":"Provider timed out"},{"code":"provider_quota","status":503,"message":"Provider quota reached"},{"code":"provider_budget_exceeded","status":503,"message":"Daily provider budget reached"},{"code":"provider_incomplete","status":502,"message":"Provider returned an incomplete result"},{"code":"studio_record_locked","status":409,"message":"Record is locked"},{"code":"studio_version_conflict","status":409,"message":"Record was changed; reload and try again"},{"code":"studio_limit_exceeded","status":413,"message":"Studio record limit reached"},{"code":"document_ocr_required","status":422,"message":"Document has no text layer; OCR is required"},{"code":"document_unreadable","status":422,"message":"Document could not be read"},{"code":"not_found","status":404,"message":"Not found"},{"code":"system_error","status":500,"message":"Internal error"}]}