Couple & Person Image API Documentation
These endpoints generate couple and single‑person images from reference photos and prompts. Use them for profile tools, avatar creators, dating apps, or any product that needs photorealistic people imagery.
Introduction
The Couple & Person Image API family lets you combine multiple reference images, pose controls, and prompts to synthesize high‑quality portraits. You can call single endpoints or send JSON batches for large‑scale jobs.
Typical use cases include:
- Generating couple portraits from separate male/female selfies.
- Creating consistent single‑person images for profiles and marketing.
- Batch‑processing multiple prompts and control images at once.
Base URL
https://taiapi.aiphotocraft.com/Authentication
All Couple & Person Image APIs require an API key, managed from the Developer Dashboard.
Header
Send the key using this header:
X-Api-Key: YOUR_API_KEYExample Request
curl -X POST "https://taiapi.aiphotocraft.com/api/person_image" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "accept: application/json" \ -H "Content-Type: multipart/form-data" \ -F "personImages[0]=@person1.jpg;type=image/jpeg" \ -F "prompt=studio portrait in soft lighting"
Backend‑only key usage
Always call these APIs from your backend or serverless environment. Do not embed the API key in public web or mobile clients.
Couple & Person Image Endpoints
Couple Image Generation
POST
/api/couple_imageGenerate a high-quality couple image from separate male and female images with optional pose control. Upload male and female reference images, and optionally a pose image.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| maleImage | file (formData) | Required | Male reference image (file alternative). |
| femaleImage | file (formData) | Required | Female reference image (file alternative). |
| poseImage | file (formData) | Optional | Optional pose control image (file alternative). |
Task Status Endpoint
GET
/api/task-status/{task_id}Get the status of a task and retrieve the processed image URL.
| Name | Type | Required | Description |
|---|---|---|---|
| task_id | string (path) | Required | The ID of the task to get the status for. |
Example Request
curl -X GET "https://taiapi.aiphotocraft.com/api/task-status/{task_id}"-H "accept: application/json"-H "X-Api-Key: YOUR_API_KEY"
Example Response
{
"image_url": "https://taiapi.aiphotocraft.com/results/swapped_image.jpg"
}Response Status Codes
| Status Code | Description |
|---|---|
| 200 | Successfully retrieved task status. |
| 400 | Bad request. |
| 401 | Unauthorized. |
Examples
import requests
url = "https://taiapi.aiphotocraft.com/api/couple_image"
headers = {
"X-Api-Key": "YOUR_API_KEY",
"accept": "application/json",
}
files = {
"maleImage": ("male.jpg", open("male.jpg", "rb"), "image/jpeg"),
"femaleImage": ("female.jpg", open("female.jpg", "rb"), "image/jpeg"),
# "poseImage": ("pose.jpg", open("pose.jpg", "rb"), "image/jpeg"), # optional
}
response = requests.post(url, headers=headers, files=files)
print(response.status_code, response.text)Couple Image Batch
POST
/api/couple_image/batchBatch couple image generation using one or more male/female subject URLs and multiple prompts, each with optional pose image. Per item you can pick which male/female index to use.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| femaleImages | array (body) | Required | Array of female subject image URLs. |
| maleImages | array (body) | Required | Array of male subject image URLs. |
| items | array (body) | Required | Array of generation items. Each item contains: femaleIndex (number), maleIndex (number), poseImage (string, optional), prompt (string). |
Task Status Endpoint
GET
/api/task-status/{task_id}Get the status of a task and retrieve the processed image URL.
| Name | Type | Required | Description |
|---|---|---|---|
| task_id | string (path) | Required | The ID of the task to get the status for. |
Example Request
curl -X GET "https://taiapi.aiphotocraft.com/api/task-status/{task_id}"-H "accept: application/json"-H "X-Api-Key: YOUR_API_KEY"
Example Response
{
"image_url": "https://taiapi.aiphotocraft.com/results/swapped_image.jpg"
}Response Status Codes
| Status Code | Description |
|---|---|
| 200 | Successfully retrieved task status. |
| 400 | Bad request. |
| 401 | Unauthorized. |
Examples
import requests
url = "https://taiapi.aiphotocraft.com/api/couple_image/batch"
headers = {
"X-Api-Key": "YOUR_API_KEY",
"accept": "application/json",
"Content-Type": "application/json",
}
data = {
"femaleImages": [
"https://example.com/female1.jpg"
],
"maleImages": [
"https://example.com/male1.jpg"
],
"items": [
{
"femaleIndex": 0,
"maleIndex": 0,
"poseImage": "https://example.com/pose.jpg",
"prompt": "happy couple at the beach"
}
]
}
response = requests.post(url, headers=headers, json=data)
print(response.status_code, response.text)Person Image
POST
/api/person_imageGenerate a single-person image from up to four reference images, with an optional control image. Provide 1–4 person reference images, an optional control image, and a text prompt that describes the desired output.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| personImages[0] | file (formData) | Required | First reference image (file alternative). |
| personImages[1] | file (formData) | Optional | Second reference image (file alternative). |
| personImages[2] | file (formData) | Optional | Third reference image (file alternative). |
| personImages[3] | file (formData) | Optional | Fourth reference image (file alternative). |
| controlImage | file (formData) | Optional | Optional control image (file alternative) to guide pose or composition. |
| prompt | string (formData) | Required | Prompt for the generated image. |
Task Status Endpoint
GET
/api/task-status/{task_id}Get the status of a task and retrieve the processed image URL.
| Name | Type | Required | Description |
|---|---|---|---|
| task_id | string (path) | Required | The ID of the task to get the status for. |
Example Request
curl -X GET "https://taiapi.aiphotocraft.com/api/task-status/{task_id}"-H "accept: application/json"-H "X-Api-Key: YOUR_API_KEY"
Example Response
{
"image_url": "https://taiapi.aiphotocraft.com/results/swapped_image.jpg"
}Response Status Codes
| Status Code | Description |
|---|---|
| 200 | Successfully retrieved task status. |
| 400 | Bad request. |
| 401 | Unauthorized. |
Examples
import requests
url = "https://taiapi.aiphotocraft.com/api/person_image"
headers = {
"X-Api-Key": "YOUR_API_KEY",
"accept": "application/json",
}
files = {
"personImages[0]": ("person1.jpg", open("person1.jpg", "rb"), "image/jpeg"),
# "personImages[1]": ("person2.jpg", open("person2.jpg", "rb"), "image/jpeg"), # optional
# "personImages[2]": ("person3.jpg", open("person3.jpg", "rb"), "image/jpeg"), # optional
# "personImages[3]": ("person4.jpg", open("person4.jpg", "rb"), "image/jpeg"), # optional
# "controlImage": ("control.jpg", open("control.jpg", "rb"), "image/jpeg"), # optional
}
data = {
"prompt": "portrait photo of the person smiling in studio lighting",
}
response = requests.post(url, headers=headers, files=files, data=data)
print(response.status_code, response.text)Person Image Batch
POST
/api/person_image_batchBatch person image generation. Submit multiple person image prompts in a single request using JSON only.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| personImages | array (body) | Required | Array of person reference image URLs used for generation. |
| promptData | array (body) | Required | Array of generation jobs. Each item contains: controlImage (string) and prompt (string). |
Task Status Endpoint
GET
/api/task-status/{task_id}Get the status of a task and retrieve the processed image URL.
| Name | Type | Required | Description |
|---|---|---|---|
| task_id | string (path) | Required | The ID of the task to get the status for. |
Example Request
curl -X GET "https://taiapi.aiphotocraft.com/api/task-status/{task_id}"-H "accept: application/json"-H "X-Api-Key: YOUR_API_KEY"
Example Response
{
"image_url": "https://taiapi.aiphotocraft.com/results/swapped_image.jpg"
}Response Status Codes
| Status Code | Description |
|---|---|
| 200 | Successfully retrieved task status. |
| 400 | Bad request. |
| 401 | Unauthorized. |
Examples
import requests
url = "https://taiapi.aiphotocraft.com/api/person_image_batch"
headers = {
"X-Api-Key": "YOUR_API_KEY",
"accept": "application/json",
"Content-Type": "application/json",
}
data = {
"personImages": [
"https://example.com/person1.jpg",
"https://example.com/person2.jpg",
],
"promptData": [
{
"controlImage": "https://example.com/control1.jpg",
"prompt": "studio portrait, soft lighting",
},
{
"controlImage": "https://example.com/control2.jpg",
"prompt": "outdoor portrait in a park",
},
],
}
response = requests.post(url, headers=headers, json=data)
print(response.status_code, response.text)