{"openapi":"3.1.0","info":{"title":"Stork Talking Photo API","version":"1.1.0","description":"Turn one photo plus speech into a lip-synced talking video. Give audio (audio_url) or text and a built-in voice (text + voice_id). Prepaid credits, 1 credit = 1 cent: standard 20 credits/min and pro 40 credits/min at 720p, billed per started 10 s. Free tier: tier \"free\", watermarked, up to 60 s, a small daily allowance shared with the website. Jobs are asynchronous: create, then poll GET ?id= or receive a signed webhook.","contact":{"email":"support@stork.ai","url":"https://www.stork.ai/developers/talking-photo-api"}},"servers":[{"url":"https://api.stork.ai"}],"security":[{"bearer":[]}],"paths":{"/api/v1/talking-photo":{"post":{"operationId":"createTalkingPhoto","summary":"Create a talking photo video","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Any unique string. A retry with the same key and body returns the first response instead of creating (and charging for) a second job. Keys live 24 h."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image_url"],"properties":{"image_url":{"type":"string","format":"uri","description":"https URL of a photo with one clear face. Max 12 MB."},"audio_url":{"type":"string","format":"uri","description":"https URL of the speech (MP3, WAV, M4A, OGG, WebM). Omit when sending text."},"text":{"type":"string","maxLength":5000,"description":"What the face says, read by voice_id. Max 5000 characters (650 on the free tier)."},"voice_id":{"type":"string","enum":["en-ava","en-leo","en-nora","en-sam","ar-layla","ar-omar","hi-priya","hi-arjun","ur-sana","ur-bilal","fr-camille","fr-karim","es-lucia","es-mateo","pt-beatriz","pt-rafael","it-giulia","it-marco","ru-anna","ru-ivan","tr-elif","tr-emre","de-lena","de-jonas","ja-yui","ja-haruto","ko-jiwoo","ko-minjun"],"description":"A built-in voice from GET /api/v1/voices. Required with text."},"quality":{"enum":["standard","pro"],"default":"standard"},"aspect_ratio":{"enum":["original","16:9","9:16","1:1"],"default":"original"},"resolution":{"enum":["480p","720p","1080p"],"default":"720p"},"tier":{"enum":["paid","free"],"default":"paid","description":"\"free\": watermarked, standard quality, 720p, up to 60 s, daily allowance."},"webhook_url":{"type":"string","format":"uri","description":"https URL; receives a signed POST when the job finishes."}}},"examples":{"text":{"summary":"Text + built-in voice","value":{"image_url":"https://www.stork.ai/samples/talking-photo/portrait.jpg","text":"Hi! I'm your new assistant. Ask me anything.","voice_id":"en-ava","aspect_ratio":"9:16"}},"audio":{"summary":"Your own audio","value":{"image_url":"https://www.stork.ai/samples/talking-photo/portrait.jpg","audio_url":"https://www.stork.ai/samples/talking-photo/hello.mp3"}}}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TalkingPhoto"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getTalkingPhoto","summary":"Get one job (?id=) or list recent jobs (?limit=)","parameters":[{"name":"id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"A job, or { object: 'list', data: [jobs] }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TalkingPhoto"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/talking-photo/estimate":{"post":{"operationId":"estimateTalkingPhoto","summary":"Price a job without creating it","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"seconds":{"type":"number"},"text":{"type":"string"},"quality":{"enum":["standard","pro"]},"resolution":{"enum":["480p","720p","1080p"]},"tier":{"enum":["paid","free"]}}}}}},"responses":{"200":{"description":"Estimate"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/voices":{"get":{"operationId":"listVoices","summary":"Built-in voices (no key needed)","security":[],"parameters":[{"name":"language","in":"query","schema":{"enum":["en","ar","hi","ur","fr","es","pt","it","ru","tr","de","ja","ko"]}}],"responses":{"200":{"description":"{ object: 'list', data: [voices] }"}}}},"/api/v1/speech":{"post":{"operationId":"createSpeech","summary":"Create a voiceover (text to speech)","description":"Text read by a built-in voice or one of your own voices, delivered as an MP3. 5 credits per minute of finished audio (1 credit = 1 cent), billed per started 10 s, minimum 5 credits a file. The estimated price plus 10% is held when the file is created; you are charged for the finished length, never more than the hold, and nothing if it fails. One file holds up to 20000 characters and 30 minutes. tier \"free\": up to 60 s, 3 files a day per account. Asynchronous: poll GET /api/v1/speech?id= until status is done, or pass webhook_url for a signed POST (event types speech.done and speech.failed). Send an Idempotency-Key header to make a retry safe: the first response is replayed and no second file is made.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text","voice_id"],"properties":{"text":{"type":"string","maxLength":20000,"description":"What the voice says, in the voice's language."},"voice_id":{"type":"string","description":"A built-in voice from GET /api/v1/voices, or the id of one of your own voices."},"tier":{"enum":["paid","free"],"default":"paid"},"webhook_url":{"type":"string","format":"uri","description":"https URL we POST the finished file to, signed like talking photo webhooks."}}},"examples":{"paid":{"value":{"text":"Welcome back to the channel. Today we are looking at three small habits.","voice_id":"en-ava"}}}}}},"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"speech"},"status":{"const":"queued"},"tier":{"enum":["paid","free"]},"estimated_seconds":{"type":"number"},"credits_held":{"type":"integer"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getSpeech","summary":"Get one voiceover, or list recent ones","parameters":[{"name":"id","in":"query","schema":{"type":"string"},"description":"Omit to list recent files."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"The file, or { object: 'list', data: [files] }","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"speech"},"status":{"enum":["queued","running","done","failed","stopped"]},"tier":{"enum":["paid","free"]},"voice_id":{"type":"string"},"characters":{"type":"integer"},"estimated_seconds":{"type":"number"},"seconds":{"type":["number","null"],"description":"Length of the finished audio."},"credits":{"type":"integer","description":"Credits charged (0 until done, 0 for free files)."},"audio_url":{"type":["string","null"],"description":"MP3, 128 kbps mono. Present when status is done."},"error":{"type":["string","null"]},"created_at":{"type":"integer","description":"Unix seconds."},"completed_at":{"type":["integer","null"]}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/speech/estimate":{"post":{"operationId":"estimateSpeech","summary":"Length and price of a text, without making anything","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string"}}}}}},"responses":{"200":{"description":"Estimate","content":{"application/json":{"schema":{"type":"object","properties":{"characters":{"type":"integer"},"seconds":{"type":"number"},"credits":{"type":"integer","description":"Expected charge."},"credits_held":{"type":"integer","description":"What is held, and the most it can cost."},"max_characters":{"type":"integer"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/singing-video":{"post":{"operationId":"createSingingVideo","summary":"Create a singing video","description":"One photo and a song become a performance video: the person sings it, filmed from several camera angles and lip-synced. 20 credits per second of delivered video (1 credit = 1 cent), 15 to 330 seconds. The price of the length ordered is held when the video is created; you are charged for the length delivered and nothing if it fails. Asynchronous and slow: a 3-minute video takes about half an hour. Poll GET ?id= or pass webhook_url. No free tier.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body returns the first response and makes no second video."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image_url","audio_url"],"properties":{"image_url":{"type":"string","format":"uri","description":"https URL of a JPG, PNG or WebP with one clear face, up to 12 MB."},"audio_url":{"type":"string","format":"uri","description":"https URL of the song (MP3, WAV, M4A, OGG, WebM), at least 15 s, up to 100 MB."},"seconds":{"type":"number","minimum":15,"maximum":330,"description":"Length of video to make, from the start of the song. Default: the whole song, up to the maximum."},"webhook_url":{"type":"string","format":"uri","description":"https URL we POST the finished video to (signed like talking photo webhooks; event type singing_video.succeeded or singing_video.failed)."}}}}}},"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"singing_video"},"status":{"enum":["queued","running","succeeded","failed"]},"seconds":{"type":["integer","null"],"description":"Length ordered."},"duration_seconds":{"type":["number","null"],"description":"Length delivered. You pay for this, never more than was ordered."},"credits_held":{"type":"integer"},"credits_charged":{"type":"integer"},"video_url":{"type":["string","null"],"description":"MP4. Present when status is succeeded."},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getSingingVideo","summary":"Get one singing video, or list recent ones","parameters":[{"name":"id","in":"query","schema":{"type":"string"},"description":"Omit to list recent videos."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"The video, or { object: 'list', data: [videos] }","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"singing_video"},"status":{"enum":["queued","running","succeeded","failed"]},"seconds":{"type":["integer","null"],"description":"Length ordered."},"duration_seconds":{"type":["number","null"],"description":"Length delivered. You pay for this, never more than was ordered."},"credits_held":{"type":"integer"},"credits_charged":{"type":"integer"},"video_url":{"type":["string","null"],"description":"MP4. Present when status is succeeded."},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/singing-video/estimate":{"post":{"operationId":"estimateSingingVideo","summary":"The price of a length, without making anything","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["seconds"],"properties":{"seconds":{"type":"number"}}}}}},"responses":{"200":{"description":"Estimate","content":{"application/json":{"schema":{"type":"object","properties":{"seconds":{"type":"integer"},"credits":{"type":"integer"},"usd":{"type":"number"},"balance_credits":{"type":"integer"},"affordable":{"type":"boolean"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"talkingPhotoFinished":{"post":{"summary":"Sent to webhook_url when a job succeeds or fails","description":"Headers: Stork-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, `${t}.${raw body}`)> and Stork-Webhook-Id (stable across retries). Your signing secret (whsec_...) is at stork.ai/dashboard/settings. Answer 2xx; failures retry after 1 min, 5 min, 30 min, 2 h and 6 h.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"enum":["talking_photo.succeeded","talking_photo.failed"]},"created_at":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/TalkingPhoto"}}}}}},"responses":{"200":{"description":"Acknowledged"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"sk_stork_... key from stork.ai/dashboard/settings"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","examples":["insufficient_credits"]},"message":{"type":"string"},"param":{"type":"string","description":"The request field the error is about, when there is one."},"request_id":{"type":"string","description":"Also in the Stork-Request-Id header. Quote it to support."},"doc_url":{"type":"string"},"top_up_url":{"type":"string"},"credits_required":{"type":"integer"},"balance_credits":{"type":"integer"},"free_remaining_today":{"type":"integer"},"auto_recharge_started":{"type":"boolean"}}}}},"TalkingPhoto":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"talking_photo"},"status":{"enum":["queued","running","succeeded","failed"]},"tier":{"enum":["paid","free"]},"watermark":{"type":"boolean","description":"true for free-tier videos (small stork.ai logo)."},"quality":{"enum":["standard","pro"]},"aspect_ratio":{"enum":["original","16:9","9:16","1:1"]},"resolution":{"enum":["480p","720p","1080p",null]},"voice_id":{"type":["string","null"]},"progress":{"type":"number","minimum":0,"maximum":1},"billed_seconds":{"type":["number","null"]},"duration_seconds":{"type":["number","null"]},"credits_held":{"type":"integer"},"credits_charged":{"type":"integer"},"video_url":{"type":["string","null"],"description":"MP4. Works for 30 days (paid) / 14 days (free)."},"video_url_expires_at":{"type":["string","null"],"format":"date-time"},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}}}}}