Siren Object SwapCreate generation

Siren Object Swap

Siren Object Swap generation API

Start a Siren Object Swap video from an uploaded source video and reference photos. The hold is taken from your balance when the request is accepted.

Siren Object Swap
POSThttps://serastudio.app/api/v1/siren-object-swap/generations

Usage 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 202 the generation is queued and billing.held_usd is held from the workspace balance. When it finishes, the final charge is billing.charged_usd and the rest is restored. A failed or canceled generation restores everything.
  • Send an Idempotency-Key header (1 to 255 ASCII characters). A retry with the same key and body returns the existing generation with 200 instead of creating another; a different body returns 422 idempotency_key_mismatch.
  • Leave out source_duration_s to hold the longest source this mode accepts (30 seconds). Sending the real length holds less.
  • Follow progress with Get generation and wait_s, or send webhook_url and 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-object-swap/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}'

Input schema

sourceobjectrequired

The video to edit: {"upload_id": "vid_..."} from Create upload, or {"generation_id": "..."} for a finished generation of this workspace.

imagesarrayrequired

1 to 8 reference photos, each {"upload_id": "img_..."}. The first photo is the object to put in.

promptstring

What to change, in plain words. Optional.

resolutionstringdefault: "720p"

Output resolution. Allowed values: "720p", "1080p".

source_duration_snumber

Length of the source video in seconds, from 4 to 30. Sets the hold; leave it out to hold 30 seconds. The finished length sets the charge either way.

webhook_urlstring

Public https URL that receives the generation when it finishes (succeeded, failed or canceled). Optional. See Webhooks.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <api-key>
Idempotency-KeyNo1 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-object-swap",
  "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.1645,
    "discount_pct": 0,
    "held_usd": 3.29,
    "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.29 here).

Errors

StatusCodeWhen it happensRetry
400invalid_jsonThe body is not a JSON object.No
400invalid_idempotency_keyThe Idempotency-Key header is empty, longer than 255 characters or not printable ASCII.No
401api_key_missingNo Bearer key was sent in the Authorization header.No
401api_key_invalidThe key is malformed or unknown.No
401api_key_revokedThe key was deleted in the console.No
401api_key_disabledThe key is disabled in the console.No
401api_key_expiredThe key is past its expiration date.No
403insufficient_scopeThe key lacks the create permission. Keys created in the console have it.No
403workspace_forbiddenThe account that owns the workspace is suspended or scheduled for deletion.No
402insufficient_balanceThe hold for this request is larger than the workspace balance. Nothing was created.No
404not_foundAn upload id does not exist in this workspace, or no file was put to its upload address.No
422file_too_largeAn uploaded file is larger than max_bytes (50 MB). error.param names it.No
422invalid_parametersource is missing. The same code and status cover every field error; error.param names the field.No
422invalid_parameterimages is missing or empty, or has more photos than this mode accepts.No
422source_too_shortsource_duration_s is under 4 seconds.No
422source_too_longsource_duration_s, or the finished generation used as a source, is over 30 seconds.No
422idempotency_key_mismatchThe same Idempotency-Key was already used with a different body.No
503temporarily_unavailableThe request could not be completed just now.Yes
500internal_errorSomething failed on our side. The request_id identifies the request.Yes
503api_unavailableThe 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"
}