Singing Video API
Send one photo and a song. Get back a performance video: the person in the photo sings it on stage, filmed from several camera angles and lip-synced. $12.00 a minute, billed by the second from prepaid credits. No subscription.
- • 20 credits a second, from 15 seconds to 5 min 30 s
- • You pay for the length delivered, nothing on failure
- • Your own song: MP3, WAV, M4A, OGG or WebM
- • Signed webhooks, idempotent creates, OpenAPI 3.1
- • Same key and credits as the other Stork APIs
- • No free tier: every video is paid
Quickstart
- Create an API key in the dashboard and add credits at stork.ai/credits.
- Create a video with a photo URL and a song URL. The answer comes back at once with an id.
- Wait. This is a slow render: a 15-second video takes about 8 minutes and a three-minute one about half an hour. Pass
webhook_urland we will call you, or poll the id once a minute.
curl -X POST https://api.stork.ai/api/v1/singing-video \
-H "Authorization: Bearer sk_stork_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"image_url": "https://www.stork.ai/samples/talking-photo/portrait.jpg",
"audio_url": "https://example.com/my-song.mp3",
"seconds": 15,
"webhook_url": "https://your-app.com/hooks/stork"
}'HTTP/1.1 202 Accepted
{
"id": "yh7051k8jdx86aafxf6yrtgnsh8jb7sx",
"object": "singing_video",
"status": "queued",
"seconds": 15,
"audio_seconds": 30.04,
"credits_held": 300,
"balance_credits": 0,
"status_url": "https://api.stork.ai/api/v1/singing-video?id=yh7051k8jdx86aafxf6yrtgnsh8jb7sx"
}curl "https://api.stork.ai/api/v1/singing-video?id=yh7051k8jdx86aafxf6yrtgnsh8jb7sx" \
-H "Authorization: Bearer sk_stork_YOUR_KEY"{
"id": "yh7051k8jdx86aafxf6yrtgnsh8jb7sx",
"object": "singing_video",
"status": "succeeded",
"seconds": 15,
"duration_seconds": 15,
"credits_held": 0,
"credits_charged": 300,
"video_url": "https://.../api/storage/edf5a5f1-....mp4",
"error": null,
"created_at": "2026-11-16T07:26:04.439Z",
"completed_at": "2026-11-16T07:34:12.299Z"
}Pricing
| Video delivered | Price |
|---|---|
| 15 seconds | $3.00 (300 credits) |
| 30 seconds | $6.00 (600 credits) |
| 1 min | $12.00 (1200 credits) |
| 2 min | $24.00 (2400 credits) |
| 3 min 23 s | $40.60 (4060 credits) |
| 5 min 30 s | $66.00 (6600 credits) |
- 1 credit = 1 cent. Credit packs start at $2.00 and never expire.
- The price of the length you order is held when the video is created (
credits_held). You are charged for the length we deliver (credits_charged), never more than the hold. - A video that fails, is refused or times out returns every credit.
POST /singing-video/estimateprices a length without making anything.
Reference
Base URL https://api.stork.ai/api/v1. Machine-readable: openapi.json (OpenAPI 3.1).
Authentication
Authorization: Bearer sk_stork_…. Keys are per account; credits belong to the account.
POST /singing-video
image_url(required): public https URL of a JPG, PNG or WebP with one clear face, up to 12 MB.audio_url(required): public https URL of the song, at least 15 seconds, up to 100 MB.seconds: how much video to make, from the start of the song, 15 to 330. Default: the whole song, up to 330 seconds.webhook_url: https URL we POST the finished video to (signed, see below).- Header
Idempotency-Key(recommended): any unique string. Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of making and charging for a second video.
GET /singing-video?id=<id> · GET /singing-video?limit=20
One video, or your recent videos newest first. status is queued, running, succeeded or failed. video_url is set on success. Store your copy.
POST /singing-video/estimate
curl -X POST https://api.stork.ai/api/v1/singing-video/estimate \
-H "Authorization: Bearer sk_stork_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"seconds": 120}'
{ "object": "estimate", "seconds": 120, "credits": 2400, "usd": 24,
"credits_per_second": 20, "min_seconds": 15, "max_seconds": 330,
"balance_credits": 1700, "affordable": true }Webhooks
With webhook_url we POST once when the video succeeds or fails. Answer 2xx; otherwise we retry after 1 min, 5 min, 30 min, 2 h and 6 h. The signature is the same as for talking photo webhooks: verify Stork-Signature with your signing secret from the dashboard, using the code in the Talking Photo API docs. A video that times out without a report from the renderer sends no webhook, so poll as a fallback.
POST https://your-app.com/hooks/stork
Content-Type: application/json
Stork-Webhook-Id: evt_yh717dydntg7p6zj0fvr2e2jax8j6zxd_succeeded
Stork-Signature: t=1763091424,v1=5f2b9c...e1
{ "id": "evt_..._succeeded", "type": "singing_video.succeeded",
"created_at": "2026-11-16T10:09:41.000Z", "data": { ...same object as GET... } }Errors
{ "error": { "code", "message", "param", "doc_url" } }. Every response carries Stork-Request-Id; quote it if you contact us. 429 and 503 carry Retry-After.
| 400 | invalid_request | The JSON body needs image_url and audio_url. |
| 400 | invalid_seconds | seconds must be from 15 to 330. |
| 400 | audio_too_short | The song must be at least 15 seconds long. |
| 400 | image_fetch_failed / audio_fetch_failed | We could not download a URL. It must be public and https. |
| 400 | image_not_an_image / audio_not_audio / audio_unreadable | The file is not an image, or not audio we can read. Use MP3, WAV, M4A, OGG or WebM. |
| 401 | missing_api_key / invalid_api_key | No key, or the key is wrong or revoked. |
| 402 | insufficient_credits | The wallet cannot cover this video. The body has credits_required, balance_credits and top_up_url. |
| 409 | idempotency_key_reused / request_in_progress | Same Idempotency-Key with a different body, or the first request is still running. |
| 413 | image_too_large / audio_too_large | Images up to 12 MB, songs up to 100 MB. |
| 429 | too_many_in_flight | Two singing videos are already being made on your account. Wait for one to finish. |
| 429 | renderer_busy | Other videos are rendering and there is no room for this one yet. Nothing was charged. Retry in 10 minutes, or order a shorter video. |
| 503 | singing_video_unavailable / probe_unavailable | Retry after the Retry-After header. |
A video can also be accepted and fail later. Its error then starts with capacity_reached, render_unavailable or render_failed, and nothing is charged.
Limits
- Up to 2 singing videos in the making at once per account.
- Rendering capacity is shared. When it is full, a create returns 429
renderer_busyand charges nothing. - Output: MP4 (H.264 + AAC). The video can be a little shorter than ordered; you pay for what is delivered.
Acceptable use
Only use faces and songs you own or have permission to use. Do not use the API to deceive, impersonate or harass anyone, and tell viewers the video is AI-generated. We may suspend keys that break these rules.
Want to try it without code? Use Stork Singing Photo. For a face that speaks instead of sings, see the Talking Photo API.
Comparing options? AI music video API prices
