Head Swap LoRA API: One-Image Head Replacement

Overview

Head Swap LoRA is an asynchronous image-to-image model for replacing a head in a target image using one head reference image.

Capability	Value
Model ID	`head-swap-LoRA`
Mode	`image-to-image`
Target image	Exactly 1 public image URL in `image_urls`
Head reference	Exactly 1 public image URL in `head_urls`
Optional seed	Non-negative integer
Result delivery	Async polling

Endpoint and authentication

Base URL:

https://api.apixo.ai/api/v1

Method	Endpoint	Purpose
`POST`	`/generateTask/head-swap-LoRA`	Submit a head swap task
`GET`	`/statusTask/head-swap-LoRA?taskId={taskId}`	Poll task status and retrieve results

All requests require your APIXO API key:

Authorization: Bearer YOUR_API_KEY

Submit requests also require:

Content-Type: application/json

Copy-paste async quickstart

curl -X POST "https://api.apixo.ai/api/v1/generateTask/head-swap-LoRA" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "image-to-image",
      "image_urls": [
        "https://example.com/target-image.png"
      ],
      "head_urls": [
        "https://example.com/head-reference.png"
      ],
      "seed": 12345
    }
  }'

Successful response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}

Poll for result

curl -X GET "https://api.apixo.ai/api/v1/statusTask/head-swap-LoRA?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/head-swap-result.png\"]}",
    "createTime": 1767965610929,
    "completeTime": 1767965652317,
    "costTime": 41388
  }
}

Parse resultJson after state becomes success:

const payload = JSON.parse(data.resultJson);
const imageUrls = payload.resultUrls;

Request body

{
  "request_type": "async",
  "input": {
    "mode": "image-to-image",
    "image_urls": [
      "https://example.com/target-image.jpg"
    ],
    "head_urls": [
      "https://example.com/head-reference.jpg"
    ],
    "seed": 42
  }
}

Parameters

string

default:"async"

required

Result delivery mode. Use async and poll with statusTask.

object

required

Head Swap LoRA input parameters.

Show properties

string

required

Generation mode. This model supports image-to-image only.

string[]

required

Target image URLs. Must contain exactly 1 non-empty public image URL.

string[]

required

Head reference image URLs. Must contain exactly 1 non-empty public image URL.

integer

Optional random seed. Use a fixed non-negative integer seed for more reproducible experiments.

Response format

POST /generateTask/head-swap-LoRA returns a task ID when the task is accepted. Poll the status endpoint until state is success or failed.

string

Unique task identifier used with the status endpoint.

string

Current task state: pending, processing, success, or failed.

string

JSON string containing output image URLs in resultUrls. Present when state is success.

string

Machine-readable failure code. Present when state is failed.

string

Human-readable failure message. Present when state is failed.

Billing

New non-LLM requests use 1 credit = $0.001. Calculate the full amount, including billable quantity and add-ons, apply the applicable account discount, then round the request total upward to the next whole credit. Agreed fixed unit prices retain their precision and replace the standard price and discount; final rounding still applies. See credit conversion and rounding. Head Swap LoRA is billed per generated image.

Unit	APIXO price
One output image	`$0.016 / image`

For the current public price, see API pricing.

Latency and polling

Use case	Recommended first poll	Poll interval
Standard head swap	10s after task creation	5s-10s

Errors and troubleshooting

Condition	What to do
Invalid or missing `mode`	Set `input.mode` to `image-to-image`
Invalid `image_urls`	Send exactly 1 public target image URL
Invalid `head_urls`	Send exactly 1 public head reference URL
Invalid `seed`	Use a non-negative integer
Task stays `processing`	Continue polling with backoff
Task returns `failed`	Check `failCode` and `failMsg`, then adjust the input or retry

See Error Codes for the full error reference.

MCP integration

The complete model schema declares result decoding in mcp.result and supported file bindings in mcp.attachments. These are client integration metadata, not generation input parameters. Attachment paths: image_urls, head_urls. Preserve the user’s file order. Model parameter validation remains on the API.

​Overview

​Endpoint and authentication

​Copy-paste async quickstart

​Poll for result

​Request body

​Parameters

​Response format

​Billing

​Latency and polling

​Errors and troubleshooting

​MCP integration

​Related links

Overview

Endpoint and authentication

Copy-paste async quickstart

Poll for result

Request body

Parameters

Response format

Billing

Latency and polling

Errors and troubleshooting

MCP integration

Related links