Head Swap LoRA

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

Head Swap LoRA is billed per generated image.

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

For the current public price, see 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.

Getting Started

Image Models

Video Models

Audio Models

Text & Utility Models

Head Swap LoRA

Overview

Endpoint and authentication

Copy-paste async quickstart

Poll for result

Request body

Parameters

Response format

Billing

Latency and polling

Errors and troubleshooting

​Overview

​Endpoint and authentication

​Copy-paste async quickstart

​Poll for result

​Request body

​Parameters

​Response format

​Billing

​Latency and polling

​Errors and troubleshooting

​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

Related links