Recast a video

1. Select an owned video, upload a file or import a direct video-file link.
2. Describe your desired cast. Choose Reskin to change the world as well. Add optional reference images for the look.
3. Choose a quality profile and, optionally, a shorter source interval. Confirm you hold the rights to remix the footage.
4. Request a quote and inspect its processing allowance and service fee. Source analysis is paid even if you decline the run.
5. Start with enough available credits to cover the quoted ceiling. Review the film, synchronized comparison and quality report when it completes.

Direct links must serve video bytes over HTTP(S), rather than a YouTube page, player page or login screen. Use upload for large files or inaccessible links. Sources and results are private by default; making them public is a separate choice.

These are brief examples, not claims that a particular result has passed review. Recast retains the original soundtrack. It does not clone voices, replace dialogue or change the spoken language. Use clear, specific appearance descriptions and owned image references to communicate your intended cast.

All profiles run unattended. Delivery is conformed to the source timeline and output dimensions; generation resolution describes the model output before that step. The default source-edit recipe uses the source motion. The alternate keyframe recipe generates motion between restyled stills and can reinterpret more of the action.

One credit is US $0.01. Recast combines metered processing with a service fee of $0.20 per transformed source second, with a $2 minimum for a newly transformed delivery. Ten transformed seconds have a $2 service fee; 30 seconds have a $6 service fee. Processing is additional, so these are not total production prices.

The tool is remix_video. Its source must be a completed, owned video UUID. First import a direct video-file URL using lib_manage, or use the library upload flow. Imports are paid and subject to fetch and size limits. An explicit project keeps the source in the intended place.

{
  "name": "lib_manage",
  "arguments": {
    "entity_type": "resource",
    "operation": "create",
    "project_id": "<owned-project-uuid>",
    "name": "courier-source.mp4",
    "mime_type": "video/mp4",
    "content_url": "https://your-media-host.example/courier-source.mp4",
    "visibility": "private"
  }
}

Use the returned resource_id in the next step. Do not pass the URL directly to Recast.

Fresh estimates return an itemized metadata.quote, a saved shot plan, an opaque quote_token and quote_expires_at in Unix seconds. The token lasts 24 hours and is bound to the account and exact creative settings.

import os
from soundside_client import SoundsideClient

client = SoundsideClient(os.environ["SOUNDSIDE_API_KEY"])
client.connect()
creative = {
    "source_resource_id": "<owned-video-uuid>",
    "brief": "An original silver-haired courier; keep the source actions, outfit and setting.",
    "mode": "recast",
    "recipe": "source_edit",
    "quality_profile": "standard",
    "range_start_sec": 0,
    "range_end_sec": 10,
}
estimate = client.call_tool("remix_video", {
    **creative,
    "rights_attested": True,
    "estimate_only": True,
    "budget_cap_credits": 2000,  # Example $20 run ceiling, not a price prediction.
}, timeout=600)
if estimate.get("success") is False:
    raise RuntimeError(estimate.get("error", "Quote failed"))
terms = estimate["metadata"]
print(terms["quote"])  # Review before purchasing.

run = client.call_tool("remix_video", {
    **creative,
    "rights_attested": True,
    "estimate_only": False,
    "quote_token": terms["quote_token"],
    "budget_cap_credits": terms["quote"]["total_credits"],
}, timeout=180)
if run.get("success") is False:
    raise RuntimeError(run.get("error", "Purchase failed"))
parent_id = run["resource_id"]
print(parent_id)

The runnable example and its sibling soundside_client.py use httpx. It provides separate quote, purchase and status commands, saves the token privately and keeps the accepted ceiling when a purchase is retried.

Preserve the settings and token together. After a lost purchase response, retry the same valid token: it returns the same parent job, with metadata.purchase_replayed=true. It does not start another attempt, even if that job failed. Changing the source, brief, profile, mode, range or references requires a new quote. A new quote and purchase can authorize a new charge.

The primary comparison places the original source on the left and Recast on the right, synchronized in one playable frame. The original is retained. Watch with sound and check hands touching objects, speaking faces, camera motion, text, background characters and cuts. A completed job means it delivered; it does not mean every quality criterion passed.

The report verifies output length through frame counts. Matching counts do not prove that each generated frame follows the source motion. Final comparison review samples at 4 fps in windows of at most 10 seconds across the delivery. Sampling and automated judging can miss defects. Read delivery_review, needs_review and unresolved_defectsbefore using the film. Shot-level evidence and attempted repairs remain available.

Costs are separated into processing_credits and service_fee_credits. The report's credits_settled records accounted costs; the account's usage records are authoritative for the settled invoice.

Check the job's status with a free on-demand library read, now or after reconnecting. A notifications/resources/updated push may also arrive, but don't rely on it. The purchase response also includes metadata.library so you can open the run's collections.

{
  "name": "lib_list",
  "arguments": {
    "entity_type": "resources",
    "resource_ids": ["<parent-resource-uuid>"]
  }
}

For a revision, pass revise_from with the owned parent UUID, brief="" and regenerate_actions containing action IDs from its plan. Review an estimate first. An empty list means pure reassembly of accepted clips. Revisions retain the parent's cast/world design and earlier resources. The report's changed_intervals are frame indices relative to the delivered film, with an exclusive end. Divide by the delivered assembly.fps to convert to seconds. The workspace keeps the source/remix comparison primary and adds a synchronized initial/revised comparison with these intervals. A visible change does not by itself demonstrate an improvement.

Selected-shot Recast revisions may reuse approved source-aligned face references when the source, action and cast still match; source motion observations refresh, and a mismatch withholds motion.

Purchase tokens currently apply to fresh jobs only. Revision calls do not have token replay protection: retain the returned parent UUID and inspect it after a timeout before submitting again. See the revision examples.

Use tools/list for the current schema and the tool reference for all parameters. Begin with a short, representative interval before committing to a longer film.