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

Start head swap generation

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 suspected minor warning (for ages 10-14). Use with caution.
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.
webhook_token	string	No	Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.

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",
  "minor_suspected_skip": false,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}'

Related Endpoints

POST/api/v1/headSwap/start

Start head swap generation

GET/api/v1/headSwap/allRecords

Get all head swap records

POST/api/v1/headSwap/batchDetail

Batch query task details

GET/api/v1/headSwap/{_id}

Get head swap task detail

DELETE/api/v1/headSwap/{_id}

Delete head swap task

Responses

200

Head swap task started successfully

400

Invalid request parameters or insufficient coins

401

Unauthorized - Invalid or missing bearer token

403

Content moderation failed (code 1003 = minor detected, code 1004 = suspected minor)