Head Swap API Documentation

Overview

Replace the head in an image with a target face while keeping the original body, clothing, lighting, and background intact.

Primary Endpoint

POST/api/v1/headSwap/start

Generate a head swap result by replacing the head in a target image/video with a source head. **Supported modes:** - **Image to Image**: Provide an image as `target_image_url` to get a head-swapped image - **Image to Video**: Provide a video as `target_image_url` to get a head-swapped video (max 15 seconds) **Content moderation:** - CSAM detection is performed on input images - If confirmed CSAM intent is detected together with age < 10, the request will be rejected with code 1003 - If suspected CSAM is detected, set `minor_suspected_skip: true` to proceed - Head swap sends no user prompt to the detector, so a low apparent age alone does not trigger 1003 **Async workflow:** 1. Task is created with status `initialized` 2. Task is queued and sent to algorithm service (status: `sent`) 3. Algorithm processes the task (status: `processing`) 4. Result is ready (status: `completed`) or failed (status: `failed`) 5. Use `/api/v1/headSwap/{_id}` to poll for status updates. ### 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: `image_url`, `target_image_url`. - 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` — Invalid request parameters or insufficient coins. - `401` — Unauthorized - Invalid or missing JWT token. - `403` — Content moderation failed (code 1003 = minor detected, code 1004 = suspected minor) ### Related Operations - `GET /api/v1/headSwap/allRecords` — Get all head swap records. - `GET /api/v1/headSwap/{_id}` — Get head swap task detail. - `DELETE /api/v1/headSwap/{_id}` — Delete head swap task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

Name	Type	Required	Description
image_url	string	Yes	URL of the source head image (the head to be transplanted)
target_image_url	string	Yes	URL of the target body image or video (where the head will be placed)
minor_suspected_skip	boolean	No	Skip the suspected CSAM warning. Use with caution.; default: false
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": {
        "image_url": {
          "type": "string",
          "description": "URL of the source head image (the head to be transplanted)",
          "format": "uri",
          "example": "https://example.com/head.jpg"
        },
        "target_image_url": {
          "type": "string",
          "description": "URL of the target body image or video (where the head will be placed)",
          "format": "uri",
          "example": "https://example.com/body.jpg"
        },
        "minor_suspected_skip": {
          "type": "boolean",
          "default": false,
          "description": "Skip the suspected CSAM warning. Use with caution.",
          "example": false
        }
      },
      "required": [
        "image_url",
        "target_image_url"
      ]
    },
    {
      "$ref": "#/components/schemas/WebhookInput"
    }
  ]
}

Response Fields

code: integer
data: object
data._id: string: Task ID for polling status
data.image_url: string: Source head image URL
data.target_image_url: string: Target body image/video URL
data.current_status: enum: initialized | sent | pending | processing | completed | failed: Current task status
data.coins: number: Coins consumed for this task
data.createdAt: string: Task creation time
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://www.a2e.com.cn/api/v1/headSwap/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "image_url": "https://example.com/head.jpg",
  "target_image_url": "https://example.com/body.jpg"
}'