Talking Video API Documentation

Overview

Re-lip-sync an existing video to a new audio source using AI-driven facial animation and motion warping.

Primary Endpoint

POST/api/v1/talkingVideo/start

Create an asynchronous talking-video task from a source video and audio. Billing uses the actual audio duration (up to 120 seconds), not the source video duration or the optional duration field. For an API quote, send input_audio_duration in generation/quote's requestBody. ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `name`, `video_url`, `audio_url`, `prompt`, `negative_prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - 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/talkingVideo/allRecords` — Get all task records. - `GET /api/v1/talkingVideo/{_id}` — Get task details. - `DELETE /api/v1/talkingVideo/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

Name	Type	Required	Description
name	string	Yes	Name of the talking video task
video_url	string	Yes	URL of the source video
audio_url	string	Yes	Required source audio URL
duration	integer	No	Fallback duration when the server cannot read audio metadata; normally billing uses the duration of audio_url.; default: 3
prompt	string	Yes	Generation prompt
negative_prompt	string	Yes	Negative prompt to avoid unwanted features
webhook_url	string	No	HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.; maxLength: 2048
webhook_token	string	No	Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.; maxLength: 256

Request schema and conditional rules

{
  "allOf": [
    {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the talking video task",
          "example": "My Talking Video"
        },
        "video_url": {
          "type": "string",
          "description": "URL of the source video",
          "example": "https://example.com/video.mp4"
        },
        "audio_url": {
          "type": "string",
          "description": "Required source audio URL",
          "example": "https://example.com/audio.mp3"
        },
        "duration": {
          "type": "integer",
          "description": "Fallback duration when the server cannot read audio metadata; normally billing uses the duration of audio_url.",
          "default": 3,
          "example": 5
        },
        "prompt": {
          "type": "string",
          "description": "Generation prompt",
          "example": "Make this person smile and speak"
        },
        "negative_prompt": {
          "type": "string",
          "description": "Negative prompt to avoid unwanted features",
          "example": "blurry, distorted"
        }
      },
      "required": [
        "name",
        "video_url",
        "audio_url",
        "prompt",
        "negative_prompt"
      ]
    },
    {
      "$ref": "#/components/schemas/WebhookInput"
    }
  ]
}

Response Fields

code: integer
data: object
data._id: string
data.name: string
data.video_url: string
data.current_status: string
data.duration: number
data.coins: number
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/talkingVideo/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My Talking Video",
  "video_url": "https://example.com/video.mp4",
  "audio_url": "https://example.com/audio.mp3",
  "duration": 5,
  "prompt": "Make this person smile and speak",
  "negative_prompt": "blurry, distorted"
}'