Image Editor API Documentation

Overview

Edit product images with the product mode. The clothing mode is deprecated; use Virtual Try-On for garment previews. This endpoint does not provide inpainting or outpainting.

Primary Endpoint

POST/api/v1/userImageEdit/start

Product editing is supported. The legacy clothing mode returns business code 100008 (endpoint deprecated); use POST /api/v1/virtualTryOn/start instead. Code 10000 is reserved for insufficient balance. ### 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: `edit_type`, `image_urls`. - 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/userImageEdit/allRecords` — Get all task records. - `GET /api/v1/userImageEdit/{_id}` — Get task details. - `DELETE /api/v1/userImageEdit/{_id}` — Delete task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).

Request Parameters

Name	Type	Required	Description
name	string	No	Name of the image edit task; default: ""
edit_type	enum: clothing \| product	Yes	Product is supported; clothing is deprecated and returns code 100008.
image_urls	array<string>	Yes	Array of image URLs to edit (minimum 2); minItems: 2
timeout	number	No	Processing timeout in seconds; default: 120
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
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 image edit task",
          "default": "",
          "example": "Product Edit"
        },
        "edit_type": {
          "type": "string",
          "enum": [
            "clothing",
            "product"
          ],
          "description": "Product is supported; clothing is deprecated and returns code 100008.",
          "example": "product"
        },
        "image_urls": {
          "type": "array",
          "minItems": 2,
          "items": {
            "type": "string",
            "format": "uri",
            "pattern": "^https?://.*"
          },
          "description": "Array of image URLs to edit (minimum 2)",
          "example": [
            "https://example.com/image1.jpg",
            "https://example.com/image2.jpg"
          ]
        },
        "timeout": {
          "type": "number",
          "default": 120,
          "description": "Processing timeout in seconds",
          "example": 120
        },
        "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."
        }
      },
      "required": [
        "edit_type",
        "image_urls"
      ]
    },
    {
      "$ref": "#/components/schemas/WebhookInput"
    }
  ]
}

Response Fields

code: integer
data: object
data._id: string
data.name: string
data.edit_type: string
data.image_urls: array<string>
data.current_status: string
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/userImageEdit/start" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "edit_type": "product",
  "image_urls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ]
}'

Related Endpoints

GET/api/v1/userImageEdit/{_id}

Get task details

POST/api/v1/userImageEdit/start

Start image editing task

GET/api/v1/userImageEdit/allRecords

Get all task records

POST/api/v1/userImageEdit/batchDetail

Batch query task details

DELETE/api/v1/userImageEdit/{_id}

Delete task

Responses

200

Product image edit task started (code 0), or deprecated clothing mode rejected (code 100008). Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.

400

Bad Request - Invalid parameters

401

Unauthorized - Invalid or missing bearer token