Skip to content

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.

Quickstart

  1. Create an API key in the dashboard and add credits at stork.ai/credits.
  2. Create a video with a photo URL and a song URL. The answer comes back at once with an id.
  3. 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_url and we will call you, or poll the id once a minute.
Create a 15-second video
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"
  }'
Response
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"
}
Check status (once a minute)
curl "https://api.stork.ai/api/v1/singing-video?id=yh7051k8jdx86aafxf6yrtgnsh8jb7sx" \
  -H "Authorization: Bearer sk_stork_YOUR_KEY"
Finished
{
  "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 deliveredPrice
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/estimate prices 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.

400invalid_requestThe JSON body needs image_url and audio_url.
400invalid_secondsseconds must be from 15 to 330.
400audio_too_shortThe song must be at least 15 seconds long.
400image_fetch_failed / audio_fetch_failedWe could not download a URL. It must be public and https.
400image_not_an_image / audio_not_audio / audio_unreadableThe file is not an image, or not audio we can read. Use MP3, WAV, M4A, OGG or WebM.
401missing_api_key / invalid_api_keyNo key, or the key is wrong or revoked.
402insufficient_creditsThe wallet cannot cover this video. The body has credits_required, balance_credits and top_up_url.
409idempotency_key_reused / request_in_progressSame Idempotency-Key with a different body, or the first request is still running.
413image_too_large / audio_too_largeImages up to 12 MB, songs up to 100 MB.
429too_many_in_flightTwo singing videos are already being made on your account. Wait for one to finish.
429renderer_busyOther videos are rendering and there is no room for this one yet. Nothing was charged. Retry in 10 minutes, or order a shorter video.
503singing_video_unavailable / probe_unavailableRetry 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_busy and 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