Skip to content
API Reference

Face Swap & Head Swap

face-swap and head-swap transplant a face — or a whole head — from a source photo onto the person in a target photo. No prompt is needed.

POST https://llm.siraya.ai/v1/images/generations

Use /v1/images/generations

Both models take their images on the generations endpoint, not /v1/images/edits. The finished image comes back in the same response — no polling. Generation typically takes 10–60 seconds.

Supported Models

Model ID Replaces Source field Output size
face-swap the face face_image follows the target image
head-swap the whole head head_image follows the target image
Authorization string Required
Your API Key (e.g., Bearer <API_KEY>).

Body

model string Required
face-swap or head-swap.
image string Required
The target — the photo whose face or head is replaced. URL or base64.
face_image string Required on face-swap
The source face to transplant. URL or base64.
head_image string Required on head-swap
The source head to transplant. URL or base64.
seed integer
Random seed for reproducibility. Omit it, or pass 0, for a random seed. 
curl https://llm.siraya.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "model": "face-swap",
    "image": "https://your-domain.com/target.jpg",
    "face_image": "https://your-domain.com/source_face.jpg"
  }'

import requests

url = "https://llm.siraya.ai/v1/images/generations"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API_KEY>"
}
data = {
    "model": "face-swap",
    "image": "https://your-domain.com/target.jpg",
    "face_image": "https://your-domain.com/source_face.jpg"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Example Response

{
  "created": 1792557768,
  "data": [
    { "url": "https://.../result_00.png" }
  ]
}

Behavior worth knowing

Both images need a real, detectable human face. Face detection runs on both inputs; cartoon or illustration-style faces fail it and the request ends in an error. Use photographs of people.

Image URLs must be public. Inputs are fetched by the model service itself; a URL behind authentication fails with a download error.

Prefer URLs over base64. The request-body size limit applies to the whole payload, and two base64 photos can exceed it.

Errors

A request-time refusal is final — retrying the same body won't help.

Status Meaning
400 Parameter validation — a missing image, face_image or head_image — or no detectable face in an input
401 Invalid API key
404 Unrecognized model code