roasOS
API referenceWorkflows

Recast a video

Recast one video with your own person and product. Send exactly one source (`source_video_url` or `source_generation_id`), a `prompt`, and at least one target: `avatar_id`, `product_id`, `references` (on the seedance-2.5-edit lane) or `elements` (Kling only). Without a target this is a plain video edit and the call is refused with `recast_target_required`. The source must be workspace-owned media or a Discover creative (`discover/items/v2/...`): a Discover ad can be recast on purpose. Any other URL is refused with `reference_media_not_workspace_owned`. The default model is seedance-2.5-edit (the preserve-video role). A body that sends `elements` and no `model` runs on kling-4, because only Kling takes elements. Other choices: kling-4, seedance-2.5-edit. Quoting, idempotency, the job envelope, webhooks and refunds are the same as the chosen model's own endpoint.

POST
/v1/workflows/recast

Recast one video with your own person and product. Send exactly one source (source_video_url or source_generation_id), a prompt, and at least one target: avatar_id, product_id, references (on the seedance-2.5-edit lane) or elements (Kling only). Without a target this is a plain video edit and the call is refused with recast_target_required.

The source must be workspace-owned media or a Discover creative (discover/items/v2/...): a Discover ad can be recast on purpose. Any other URL is refused with reference_media_not_workspace_owned.

The default model is seedance-2.5-edit (the preserve-video role). A body that sends elements and no model runs on kling-4, because only Kling takes elements. Other choices: kling-4, seedance-2.5-edit. Quoting, idempotency, the job envelope, webhooks and refunds are the same as the chosen model's own endpoint.

Authorization

bearerAuth
AuthorizationBearer <token>

API key authentication. Use your API key as the bearer token: Authorization: Bearer roasos_sk_...

In: header

Header Parameters

Idempotency-Key*string

A unique string that makes retries safe. Any value 16-255 characters; reuse it only when retrying the exact same request.

Match^[A-Za-z0-9._:-]+$
Length16 <= length <= 255
X-RoasOS-Project?string

Optional label to group this request under one of your projects. Appears in your usage records.

Match^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
Length1 <= length <= 64
X-RoasOS-Cost-Center?string

Optional label to attribute this request to a cost center. Appears in your usage records.

Match^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
Length1 <= length <= 64

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/workflows/recast" \  -H "Idempotency-Key: stringstringstri" \  -H "Content-Type: application/json" \  -d '{}'
{  "data": {    "kind": "quote",    "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",    "credits": 0,    "expires_at": "string",    "pricing_version": "string",    "confirmation": {      "property1": null,      "property2": null    }  }}

Get the finished ad analysis

The analysis document. An analysis that is not finished answers 409 analysis_not_completed.

Animate a still

Turn one still your workspace owns into one video. Send exactly one source (`image_url` or `upload_id`) and a `prompt`, or set `auto_prompt: true` to analyze the still first and derive the prompt from it — that analysis is billed on top of the video. The default model is seedance-2.5 (the animate-still role); `kling-4` is the other choice. roasOS never switches the model for you. One call makes one video. There is no fan-out.