Video Twin API Documentation

Overview

Build a personalised video twin - a digital double trained on your own footage - that can speak and present content on your behalf with natural motion.

Primary Endpoint

POST/api/v1/userVideoTwin/startTraining

An image avatar is billed using the current image_twin price when created (code default: 30 coins; dynamic settings can override). A video source with skipPreview=false (the default) first creates a usable avatar without a training charge; a returned anchor_id only confirms avatar creation. Video deep training uses the current video_twin price when started later via continueTraining (code default: 100 coins; dynamic settings can override). Set skipPreview=true to start deep training automatically and charge at creation. Training failure may trigger a refund according to task status. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body when using the optional controls documented in the request schema. ### Behavior - Validates the submitted payload and performs the operation described by the request schema. - Conditional fields, mutually exclusive inputs, limits, and defaults are enforced as documented by their schemas. ### Response - On `200`, consume the fields defined by that response schema below. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/userVideoTwin/records` — Get video twin records. - `POST /api/v1/userVideoTwin/upload` — Deprecated video twin upload. - `POST /api/v1/userVideoTwin/training` — Deprecated video twin training. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

Name	Type	Required	Description
name	string	No	Name for the video twin
image_url	string	No	URL of the source image
video_url	string	No	URL of the source video
skipPreview	boolean	No	Start video deep training automatically and charge the current video_twin price at creation. Only applies to a video source.; default: false
video_background_image	string	No	URL of background image
video_background_color	string	No	Background color in RGBA format
minor_suspected_skip	boolean	No	Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block.; default: false

Request schema and conditional rules

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Name for the video twin",
      "example": "My Video Twin"
    },
    "image_url": {
      "type": "string",
      "description": "URL of the source image",
      "example": "https://example.com/face.jpg"
    },
    "video_url": {
      "type": "string",
      "description": "URL of the source video",
      "example": "https://example.com/video.mp4"
    },
    "skipPreview": {
      "type": "boolean",
      "default": false,
      "description": "Start video deep training automatically and charge the current video_twin price at creation. Only applies to a video source.",
      "example": false
    },
    "video_background_image": {
      "type": "string",
      "description": "URL of background image",
      "example": "https://example.com/bg.jpg"
    },
    "video_background_color": {
      "type": "string",
      "description": "Background color in RGBA format",
      "example": "rgba(255,255,255,1)"
    },
    "minor_suspected_skip": {
      "type": "boolean",
      "default": false,
      "description": "Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block.",
      "example": false
    }
  },
  "required": [],
  "example": {}
}

Response Fields

code: integer
data: object
data._id: string: Video twin ID
data.name: string
data.gender: string
data.image_url: string
data.video_url: string
data.current_status: enum: initialized | sent | pending | processing | copying | completed | failed: completed and failed are terminal states
data.failed_code: string
data.failed_message: string
data.failed_reason: string: Public failure reason, present only when training failed
data.preview_result_url: string: Preview video URL; falls back to video_url once completed
data.image_result_url: string
data.video_backgroud_image: string: Background image URL (field name keeps the historical spelling)
data.video_backgroud_color: string: Background color in RGBA format
data.skipPreview: boolean
data.isSilent: boolean
data.hasVoiceClone: boolean
data.hasVideoClone: boolean
data.hasEyecontact: boolean
data.eyecontact_result_url: string
data.custom_anchor_id: string: Custom avatar created from this twin
data.anchor_id: string
data.user_voice_id: string: Cloned voice linked to this twin
data.coins: number
data.hasRefundCoin: boolean
trace_id: string: Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.

Request Example

curl -X POST "https://headswap.app/api/v1/userVideoTwin/startTraining" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'