Recast a video

Recast is the identity/product replacement path for Preserve video. It edits footage your workspace owns and requests that the original camera, motion, cuts and timing remain. Review the result for fidelity; matching frames or output length is not guaranteed. For a new script and storyboard, choose Rebuild ad.

Recast runs on seedance-2.5-edit by default. A request that sends elements and no model runs on kling-4, because only Kling accepts identity elements. model chooses the model: seedance-2.5-edit or kling-4. The quote, the idempotency key, the job envelope, the webhook and the refund are the same as for POST /v1/video-edit/kling-4.

1. Choose the source video

Send exactly one source.

source_generation_id resolves to the output URL of that job. Use it to recast a clip that roasOS made for you, without copying the URL.

On kling-4, the source must be 3 to 30 seconds long, at most 100 MiB, at least 700 px per side, and video/mp4. On seedance-2.5-edit, the source must be 4 to 30 seconds long and at most 100 MiB.

2. Choose the target

Send at least one of these three fields. Without one of them the call is a plain video edit, so roasOS refuses it with 400 recast_target_required.

Add optional references for a look, such as a season or a location. On seedance-2.5-edit, your references, the product images and the avatar share 9 image slots. On the Kling tiers, explicit elements, a saved avatar and all reference images share four slots. The avatar counts as one identity element, and each image resolved from product_id counts as one appearance reference.

A body that carries elements needs a consent record. Send media_rights with it, or roasOS answers 400 media_rights_required. A recast that casts only avatar_id or product_id needs none. Refer to Recast an actor.

Name each identity in the prompt

The provider needs every identity element named one time in the prompt.

On seedance-2.5-edit (the default):

• @Image1 to @Image9 are the images, in this order: your references, the product images, then the avatar.
• Write the tags yourself.

On kling-4:

• @Video1 is the source clip.
• @Element1 to @Element7 are the elements, in order.
• @Image1 to @Image9 are the references, in order.
• roasOS appends the tag for avatar_id when your prompt does not carry it. Write the other tags yourself.

Name the requested change, then ask to preserve the remaining motion, camera, cuts, timing and existing captions. Keep generation-only no-text suffixes off an edit.

3. Quote

This example names kling-4, so the avatar binds as @Element1.

curl -X POST https://api.roasos.com/v1/workflows/recast \
  -H "Authorization: Bearer roasos_sk_..." \
  -H "Idempotency-Key: recast-kitchen-cut-001" \
  -H "Content-Type: application/json" \
  -d '{
    "source_generation_id": "3d2f7b90-6c11-4a8d-9b02-77e5a1c4d380",
    "prompt": "Replace the woman with @Element1. Keep the product, the hands and the lighting the same.",
    "avatar_id": "9c17ab42-0b53-4d1e-8f7a-2c9b6e40a115",
    "product_id": "5e6b3311-7a2c-4f19-b3d8-0c41e7f92a63",
    "model": "kling-4",
    "quote_only": true
  }'

{
  "data": {
    "kind": "quote",
    "quote_id": "c4a0e918-...",
    "credits": 17,
    "expires_at": "2026-08-21T11:12:19.000Z",
    "pricing_version": "customer-pricing@2026-10-30.v14",
    "confirmation": {
      "model": "kling-4",
      "mode": "edit",
      "duration_seconds": 5,
      "reference_count": 2
    }
  }
}

Read confirmation. It states what roasOS understood. Credits are reserved from the measured source duration. Completion refunds credits proportionally for shorter output and caps longer output at the approved quote; the source is not billed again as an input-video offset.

4. Confirm

Send the same body with the quote_id. Use the same idempotency key. Add webhook_url when you do not want to poll.

curl -X POST https://api.roasos.com/v1/workflows/recast \
  -H "Authorization: Bearer roasos_sk_..." \
  -H "Idempotency-Key: recast-kitchen-cut-001" \
  -H "Content-Type: application/json" \
  -d '{
    "source_generation_id": "3d2f7b90-6c11-4a8d-9b02-77e5a1c4d380",
    "prompt": "Replace the woman with @Element1. Keep the product, the hands and the lighting the same.",
    "avatar_id": "9c17ab42-0b53-4d1e-8f7a-2c9b6e40a115",
    "product_id": "5e6b3311-7a2c-4f19-b3d8-0c41e7f92a63",
    "model": "kling-4",
    "quote_id": "c4a0e918-..."
  }'

The answer is 201 with the standard job envelope.

{
  "data": {
    "id": "7b52d0c4-...",
    "kind": "video",
    "model": "kling-4",
    "status": "queued",
    "credits_reserved": 17,
    "created_at": "2026-08-21T11:02:31Z",
    "links": {
      "self": "/v1/jobs/7b52d0c4-...",
      "status": "/v1/jobs/7b52d0c4-.../status",
      "result": "/v1/jobs/7b52d0c4-.../result",
      "events": "/v1/jobs/7b52d0c4-.../events"
    }
  }
}

5. Poll the job

curl https://api.roasos.com/v1/jobs/7b52d0c4-.../status \
  -H "Authorization: Bearer roasos_sk_..."

A recast is an ordinary job, so it carries the five job statuses. Poll every few seconds until the status is completed, failed or canceled. Refer to Jobs and to Webhooks.

6. Read the result

curl https://api.roasos.com/v1/jobs/7b52d0c4-.../result \
  -H "Authorization: Bearer roasos_sk_..."

{
  "data": { "url": "https://cdn.roasos.com/workspaces/.../recast.mp4" }
}

The URL is immutable. Send it as the media input of your next call.

Rights

You may recast only a video that your workspace owns.

roasOS checks the source against the workspace media rules before it prices anything. An immutable object under workspaces/… or uploads/… on https://cdn.roasos.com passes. Every other URL fails with 400 reference_media_not_workspace_owned.

Price

The quote reserves credits from the measured source length.

Choose the tier

model chooses the model. The default is seedance-2.5-edit, the preserve-video role in roasos_get_catalog. A request with elements and no model uses kling-4.

Both models bill the source seconds and the output seconds. The Kling 4.0 values are at 1080p, its default tier. A longer output cannot exceed the approved quote. The full tables are on the model pages: Kling 4.0 Edit.

seedance-2.5-edit takes a source up to 30 seconds and up to 9 reference images. On it, references alone is a valid target, and elements is refused. The model page states its price: Seedance 2.5 Edit.

Limits

• The source must be 3 to 30 seconds on kling-4 and 4 to 30 seconds on seedance-2.5-edit. A longer clip is 400 recast_source_too_long.
• Keep the prompt at 2,500 characters or fewer. Every recast model holds the same limit.
• On kling-4, the edit has no audio control. Do not promise the original sound.
• The source length sets the reservation. Review output duration: shorter output receives a proportional refund, and longer output cannot exceed the approved quote.

Errors

Refer to Errors.

From an agent

The MCP tool is roasos_recast_video. The quote rule is the same. Refer to Connect an AI agent (MCP).