Siren Motion Transfer
Siren Motion Transfer generation API
Start a Siren Motion Transfer video from an uploaded source video and reference photos. The hold is taken from your balance when the request is accepted.
https://serastudio.app/api/v1/siren/generationsUsage notes
- The key needs the create permission. Keys created in the console have it.
- Upload the source video and the photos first with Create upload. A finished generation can also be the source (
generation_id). - On
202the generation is queued andbilling.held_usdis held from the workspace balance. When it finishes, the final charge isbilling.charged_usdand the rest is restored. A failed or canceled generation restores everything. - Send an
Idempotency-Keyheader (1 to 255 ASCII characters). A retry with the same key and body returns the existing generation with200instead of creating another; a different body returns422 idempotency_key_mismatch. - Leave out
source_duration_sto hold the longest source this mode accepts (15 seconds). Sending the real length holds less. - Follow progress with Get generation and
wait_s, or sendwebhook_urland the generation is posted to your server when it finishes. See Webhooks. - The endpoint ignores fields it does not know.
Quick start
curl https://serastudio.app/api/v1/siren/generations \
-H "Authorization: Bearer $SERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1182" \
-d '{"source": {"upload_id": "vid_…"}, "images": [{"upload_id": "img_…"}], "resolution": "720p", "source_duration_s": 9.4}'import os, requests
r = requests.post(
"https://serastudio.app/api/v1/siren/generations",
headers={"Authorization": f"Bearer {os.environ['SERA_API_KEY']}", "Content-Type": "application/json", "Idempotency-Key": "order-1182"},
json={"source": {"upload_id": "vid_…"}, "images": [{"upload_id": "img_…"}], "resolution": "720p", "source_duration_s": 9.4},
)
print(r.json()["id"], r.json()["status"])const res = await fetch('https://serastudio.app/api/v1/siren/generations', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.SERA_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'order-1182',
},
body: JSON.stringify({ source: { upload_id: 'vid_…' }, images: [{ upload_id: 'img_…' }], resolution: '720p', source_duration_s: 9.4 }),
});
const generation = await res.json();
console.log(generation.id, generation.status);Input schema
sourceobjectrequiredThe video to edit: {"upload_id": "vid_..."} from Create upload, or {"generation_id": "..."} for a finished generation of this workspace.
imagesarrayrequired1 to 8 reference photos, each {"upload_id": "img_..."}.
promptstringWhat to change, in plain words. Optional.
resolutionstringdefault: "480p"Output resolution. Allowed values: "480p", "720p", "1080p".
source_duration_snumberLength of the source video in seconds, from 1 to 15. Sets the hold; leave it out to hold 15 seconds. The finished length sets the charge either way.
webhook_urlstringPublic https URL that receives the generation when it finishes (succeeded, failed or canceled). Optional. See Webhooks.
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <api-key> |
Idempotency-Key | No | 1 to 255 printable ASCII characters. Same key and body: the same generation comes back with 200. |
Response
A new generation returns 202 with the generation object:
{
"id": "0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70",
"object": "generation",
"model": "siren",
"status": "queued",
"created_at": "2026-11-09T05:11:02.000Z",
"finished_at": null,
"input": {
"source": {
"upload_id": "vid_3f2c7a9e-5d1b-4c8e-9f20-7a6b5c4d3e21"
},
"images": [
{
"upload_id": "img_9a0b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d"
}
],
"prompt": "Keep the motion.",
"resolution": "720p",
"source_duration_s": 9.4,
"webhook_url": null
},
"progress": {
"stage": "queued",
"percent": 0
},
"output": null,
"output_deleted": false,
"error": null,
"billing": {
"currency": "usd",
"resolution": "720p",
"usd_per_second": 0.175,
"discount_pct": 0,
"held_usd": 3.5,
"charged_usd": null,
"restored_usd": 0,
"settled": false
},
"idempotency_key": "order-1182"
}See Get generation for every field. billing.held_usd equals the estimate's max_usd for the same resolution and length ($3.50 here).
Errors
| Status | Code | When it happens | Retry |
|---|---|---|---|
400 | invalid_json | The body is not a JSON object. | No |
400 | invalid_idempotency_key | The Idempotency-Key header is empty, longer than 255 characters or not printable ASCII. | No |
401 | api_key_missing | No Bearer key was sent in the Authorization header. | No |
401 | api_key_invalid | The key is malformed or unknown. | No |
401 | api_key_revoked | The key was deleted in the console. | No |
401 | api_key_disabled | The key is disabled in the console. | No |
401 | api_key_expired | The key is past its expiration date. | No |
403 | insufficient_scope | The key lacks the create permission. Keys created in the console have it. | No |
403 | workspace_forbidden | The account that owns the workspace is suspended or scheduled for deletion. | No |
402 | insufficient_balance | The hold for this request is larger than the workspace balance. Nothing was created. | No |
404 | not_found | An upload id does not exist in this workspace, or no file was put to its upload address. | No |
422 | file_too_large | An uploaded file is larger than max_bytes (50 MB). error.param names it. | No |
422 | invalid_parameter | source is missing. The same code and status cover every field error; error.param names the field. | No |
422 | invalid_parameter | images is missing or empty, or has more photos than this mode accepts. | No |
422 | source_too_short | source_duration_s is under 1 second. | No |
422 | source_too_long | source_duration_s, or the finished generation used as a source, is over 15 seconds. | No |
422 | idempotency_key_mismatch | The same Idempotency-Key was already used with a different body. | No |
503 | temporarily_unavailable | The request could not be completed just now. | Yes |
500 | internal_error | Something failed on our side. The request_id identifies the request. | Yes |
503 | api_unavailable | The API is turned off. | No |
Not enough balance, for example, returns 402 and creates nothing:
{
"error": {
"type": "billing",
"code": "insufficient_balance",
"message": "This request holds $3.50 but the workspace balance is $1.20.",
"fix": "Add funds in the console at /developers/billing, or send a shorter source.",
"charged": false,
"retryable": false
},
"request_id": "req_k38ss8hmb36g9308sy351ot3yi"
}