Video clone

POST /v1/videos/clone takes a reference video and a request such as “replace the main character with the cat in the reference image”, and makes a new video with the same pacing, shots and motion. Each version of the result is a revision, and each revision is a workflow run (geekidea/video-clone). Progress, confirmation, redo and cancellation use the /v1/workflow_runs endpoints.

Create a video clone

curl https://api.geekidea.ai/v1/videos/clone \
  -H "Authorization: Bearer $GEEKIDEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: clone-1042" \
  -d '{
    "source_file_id": "file-0192f1c3a7b87c3e9a4f5b6c7d8e9f01",
    "prompt": "Replace the main character with the orange cat in the reference image and move the scene to a beach",
    "reference_file_ids": ["file-0192f1c3a7b87c3e9a4f5b6c7d8e9f02"],
    "understand_model": "google/gemini-3-pro-preview",
    "image_model": "openai/gpt-image-2",
    "video_model": "bytedance/seedance-1.5-pro",
    "max_duration_seconds": 60,
    "budget_usd": 20
  }'

{
  "id": "vclone_0192f1c3a7b87c3e9a4f5b6c7d8e9f01",
  "object": "video.clone",
  "status": "producing",
  "current_revision_no": 1,
  "source": { "file_id": "file-0192f1c3a7b87c3e9a4f5b6c7d8e9f01", "url": "https://…", "mime": "video/mp4", "width": 1080, "height": 1920 },
  "source_url": null,
  "source_duration_ms": null,
  "prompt": "Replace the main character with the orange cat in the reference image and move the scene to a beach",
  "models": { "understand": "google/gemini-3-pro-preview", "image": "openai/gpt-image-2", "video": "bytedance/seedance-1.5-pro", "voice": null },
  "aspect_ratio": "auto",
  "resolution": "720p",
  "max_duration_seconds": 60,
  "audio_policy": "keep",
  "voice": null,
  "auto_confirm": false,
  "revisions": [
    { "revision_no": 1, "base_revision_no": null, "status": "producing", "run_id": "run_0192f1c3a7b87c3e9a4f5b6c7d8e9f03", "progress": 0, "final_video": null, "created_at": 1791425100 }
  ],
  "end_user": null,
  "metadata": null,
  "created_at": 1791425100
}

Follow the revision with GET /v1/workflow_runs/{run_id}, its event stream or webhooks.

Field	Description
`source_file_id`	A reference video uploaded to this project with `POST /v1/files`: mp4, mov or webm, up to 5 minutes
`source_url`	Or a public http(s) link to the video file, downloaded in the `import` step: up to 200 MB and 5 minutes. Web pages are not accepted
`prompt`	Required. What to change, up to 4,000 characters
`reference_file_ids`	Up to 12 uploaded images, numbered in this order in the understanding and plan
`understand_model`	Required. Text model that watches the reference video and writes the plan. It must accept video input
`image_model`	Required. Image model for subject sheets and frames
`video_model`	Required. Video model for the shot clips
`aspect_ratio`	`auto` (default, nearest to the reference video), `9:16`, `16:9` or `1:1`. The video model must support an explicit value
`resolution`	`720p` (default) or `1080p`
`max_duration_seconds`	Maximum length of the result, 1–300, default 300. Longer reference videos are cut down in the plan
`audio_policy`	`keep` (default, original audio), `mute`, `dub` (new voice-over) or `generated` (audio generated by the video model)
`voice_model`	Speech model for `dub`, default `qwen/qwen3-tts-flash`
`voice`	Voice for the voice-over; the model’s default when omitted
`auto_confirm`	Don’t stop for confirmation after each step
`budget_usd`	Budget for this revision in USD, see Budget
`end_user`	Your end-user identifier, up to 128 characters
`metadata`	Up to 16 string key–value pairs

Give exactly one of source_file_id and source_url. A source that can’t be used returns 400 video_clone_source_invalid; an understand_model without video input returns 400 input_not_supported. POST /v1/videos/clone/quote takes the same body and saves nothing. It returns estimated_cost_usd, the amount held when the task is created (split into model_cost_usd and fee_usd), the steps in that first segment, total_cost_usd for the whole of revision 1, source_duration_ms the estimate is based on, and within_budget when you sent budget_usd. Before the plan exists the number of shots is unknown, so it is estimated from the reference video length (probed for source_file_id; for source_url, the smaller of max_duration_seconds and 60 seconds) and the video model’s default clip length.

Steps

Step	Does	Stops for confirmation
`import`	Downloads `source_url`. Runs only when `source_url` is given	No
`understand`	Watches the reference video and writes the understanding: summary, subjects, events, on-screen text, speech, the edits to make and what to keep	Yes
`plan`	Writes the production plan: shots, generation modes, images to draw	Yes
`images`	Draws subject sheets and frames	Yes
`video`	Generates each shot’s clip; shots with motion control first extract a depth video from the reference	Yes
`compose`	Cuts the final video. With `audio_policy: "dub"`, records the voice-over first	No

With auto_confirm: true no step stops. A new revision skips import and understand and reuses the understanding of the revision it is based on. Skipped steps are not charged. When the run stops in waiting_input, review the revision, edit the understanding or plan if you like, then call POST /v1/workflow_runs/{id}/confirm. Redo a step with POST /v1/workflow_runs/{id}/steps/{stepKey}/redo and cancel with POST /v1/workflow_runs/{id}/cancel.

Tasks and revisions

Endpoint	Description
`GET /v1/videos/clone`	Tasks in the project, newest first. Filter with `end_user`, page with `after` (the last task ID) and `limit` (1–100, default 20)
`GET /v1/videos/clone/{id}`	The task with the settings of the current revision, and every revision’s status and final video
`POST /v1/videos/clone/{id}/revisions`	Start a new revision
`GET /v1/videos/clone/{id}/revisions/{no}`	A revision’s run, brief, understanding, plan, shots, every asset candidate, the final video and its timeline
`PUT /v1/videos/clone/{id}/revisions/{no}/understanding`	Replace the understanding
`PUT /v1/videos/clone/{id}/revisions/{no}/plan`	Replace the plan

Task status follows the current revision: draft, producing, waiting_input, completed, failed or cancelled.

New revisions

curl https://api.geekidea.ai/v1/videos/clone/vclone_0192f1c3a7b87c3e9a4f5b6c7d8e9f01/revisions \
  -H "Authorization: Bearer $GEEKIDEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: clone-1042-r2" \
  -d '{"prompt": "Make the cat a shiba inu, keep everything else"}'

The body is optional. base_revision_no picks the revision to start from (default: the current one; it must already have an understanding). prompt, reference_file_ids (replaces the whole list), understand_model, image_model, video_model, aspect_ratio, resolution, max_duration_seconds, audio_policy, voice_model, voice and budget_usd are as above; fields you leave out keep the base revision’s values. The reference video stays the same; to use another one, create a new task. The new revision becomes current. It returns 409 workflow_invalid_state while the current revision is running.

Edit the understanding and plan

Send {"payload": { … }} with the whole new content, in the same structure as understanding or plan in the revision detail.

Replacing the understanding resets plan and the later steps.
Replacing the plan first fits it to the video model’s durations and the length limit, then resets images and the later steps.

The run goes back to waiting_input; confirm to continue. Invalid content returns 400 invalid_parameter; a running run returns 409 workflow_invalid_state.

Assets

Images, depth videos, clips and the voice-over are asset candidates (casset_…). Each belongs to a slot (for example image:s01_first or clip:s01), and the selected candidate of a slot is the one used. role is subject, frame, source_frame, motion, clip or voice.

Endpoint	Description
`POST /v1/videos/clone/{id}/assets/{asset_id}/regenerate`	Regenerate one subject sheet, frame or shot clip. Optional body: `prompt` (replaces the previous prompt), `feedback` (appended to it)
`POST /v1/videos/clone/{id}/assets/{asset_id}/adopt`	Select a succeeded candidate for its slot
`POST /v1/videos/clone/{id}/assets/{asset_id}/upload`	Replace a subject sheet or frame with an image uploaded through `POST /v1/files`. Body: `file_id`

Regenerate opens its own charge (kind media) for that one asset’s model cost and feature fee (one image, or the shot’s seconds), and does not reset any step. When it succeeds the new candidate is selected.
Upload adds the image as a new selected candidate in the slot of asset_id, free of charge.
When a candidate is selected, assets made from it are marked stale: true.
Regenerate, adopt and upload return 409 workflow_invalid_state while the run is running. Regenerate also returns 409 while the slot is already generating.

An asset has id, revision_no, kind (image, video, audio or depth), role, slot, shot_key, subject_key, status (generating, succeeded or failed), selected, stale, source (generated, regenerated, uploaded, extracted or dubbed), file, generation_id, prompt, feedback, error_code and created_at. File urls are signed and expire; query again for fresh links.

Pricing

A revision costs the model calls its steps make, at the same price as calling the models directly, plus a feature fee per step. The depth extraction and the voice-over are billed as model cost only; they have no feature fee of their own. See Billing for the current feature fees.

Get started

Generate

Workflows

Async and webhooks

Account

Create a video clone

Steps

Tasks and revisions

New revisions

Edit the understanding and plan

Assets

Pricing

​Create a video clone

​Steps

​Tasks and revisions

​New revisions

​Edit the understanding and plan

​Assets

​Pricing

Create a video clone

Steps

Tasks and revisions

New revisions

Edit the understanding and plan

Assets

Pricing