Identity

Core identity primitives: face swap, identity lock, identity replace, instamodel, virtual try-on, and voice clone. Pair any of these with an identity profile for consistent results.

Every endpoint returns a job_id and has a matching GET …/status/{job_id} route, see Jobs. output_format (webp, jpeg, or png), callback_url (a webhook), and server_id (Enterprise pod pin) are accepted by every image endpoint below.

Faceswap

POST /identity/faceswap/image/v1, swap the source face onto the target image.

cURL

curl -X POST https://api.imagepipeline.io/identity/faceswap/image/v1 \
  -H "X-API-Key: $IMAGEPIPELINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "https://.../scene.webp",
  "source": "https://.../face.webp",
  "upscale": 1.5,
  "restore_weight": 0.5
}'

JavaScript

const res = await fetch("https://api.imagepipeline.io/identity/faceswap/image/v1", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.IMAGEPIPELINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "target": "https://.../scene.webp",
  "source": "https://.../face.webp",
  "upscale": 1.5,
  "restore_weight": 0.5
}),
});
const { job_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.imagepipeline.io/identity/faceswap/image/v1",
    headers={"X-API-Key": API_KEY},
    json={
  "target": "https://.../scene.webp",
  "source": "https://.../face.webp",
  "upscale": 1.5,
  "restore_weight": 0.5
},
)
job_id = res.json()["job_id"]

Java

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.imagepipeline.io/identity/faceswap/image/v1"))
    .header("X-API-Key", System.getenv("IMAGEPIPELINE_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
{
  "target": "https://.../scene.webp",
  "source": "https://.../face.webp",
  "upscale": 1.5,
  "restore_weight": 0.5
}
"""))
    .build();
HttpResponse<String> res = client.send(req, BodyHandlers.ofString());

Field	Type	Default	Notes
target	string	,	Required. Public URL of the target image (body/scene).
source	string	,	Required. Public URL of the source face to swap in.
upscale	number	1.5	Output upscale factor (1.0 to 4.0).
restore_weight	number	0.5	Face restoration strength (0.0 to 1.0). Higher = sharper.
palette	string[]	,	Brand colours as hex codes, blended into the output.
output_format	string	webp	webp, jpeg, or png.
profile_id	string	,	Apply an identity profile.
callback_url	string	,	Webhook URL on completion.
server_id	string	,	Enterprise: pin to a dedicated pod.

Response — poll GET …/status/{job_id} until status is completed:

{
  "job_id": "job_8f2a3c1b",
  "status": "completed",
  "result_url": "https://cdn.imagepipeline.io/o/8f2a3c1b.webp",
  "processing_time_seconds": 22.1,
  "balance_remaining_usd": 187.52
}

Identity Lock

POST /identity/lock/image/v1, generate a new image that preserves a person's identity from input_image, guided by prompt.

cURL

curl -X POST https://api.imagepipeline.io/identity/lock/image/v1 \
  -H "X-API-Key: $IMAGEPIPELINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input_image": "https://.../face.webp",
  "prompt": "as a firefighter, photoreal"
}'

JavaScript

const res = await fetch("https://api.imagepipeline.io/identity/lock/image/v1", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.IMAGEPIPELINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "input_image": "https://.../face.webp",
  "prompt": "as a firefighter, photoreal"
}),
});
const { job_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.imagepipeline.io/identity/lock/image/v1",
    headers={"X-API-Key": API_KEY},
    json={
  "input_image": "https://.../face.webp",
  "prompt": "as a firefighter, photoreal"
},
)
job_id = res.json()["job_id"]

Java

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.imagepipeline.io/identity/lock/image/v1"))
    .header("X-API-Key", System.getenv("IMAGEPIPELINE_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
{
  "input_image": "https://.../face.webp",
  "prompt": "as a firefighter, photoreal"
}
"""))
    .build();
HttpResponse<String> res = client.send(req, BodyHandlers.ofString());

Field	Type	Default	Notes
prompt	string	,	Required. Describe the desired scene or appearance.
input_image	string	,	Public URL of the source image whose identity is locked.
width / height	integer	1024	Output dimensions (max 2048).
negative_prompt	string	,	Negative prompt; activates classifier-free guidance when set.
num_inference_steps	integer	model	Diffusion steps (1 to 100). Higher = better, slower.
guidance_scale	number	model	Classifier-free guidance scale (1.0 to 20.0).
seed	integer	-1	-1 randomizes; set a value for reproducibility.
palette	string[]	,	Brand colours as hex codes.
output_format	string	webp	webp, jpeg, or png.
profile_id	string	,	Apply an identity profile.
callback_url	string	,	Webhook URL on completion.
server_id	string	,	Enterprise: pin to a dedicated pod.

Response — poll GET …/status/{job_id} until status is completed:

{
  "job_id": "job_4d9e6a72",
  "status": "completed",
  "result_url": "https://cdn.imagepipeline.io/o/4d9e6a72.webp",
  "processing_time_seconds": 38.4,
  "balance_remaining_usd": 187.52
}

Identity Replace

POST /identity/replace/image/v1, replace the identity in an existing image while keeping pose and composition.

cURL

curl -X POST https://api.imagepipeline.io/identity/replace/image/v1 \
  -H "X-API-Key: $IMAGEPIPELINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input_image": "https://.../photo.webp",
  "prompt": "caucasian woman with green eyes"
}'

JavaScript

const res = await fetch("https://api.imagepipeline.io/identity/replace/image/v1", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.IMAGEPIPELINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "input_image": "https://.../photo.webp",
  "prompt": "caucasian woman with green eyes"
}),
});
const { job_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.imagepipeline.io/identity/replace/image/v1",
    headers={"X-API-Key": API_KEY},
    json={
  "input_image": "https://.../photo.webp",
  "prompt": "caucasian woman with green eyes"
},
)
job_id = res.json()["job_id"]

Java

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.imagepipeline.io/identity/replace/image/v1"))
    .header("X-API-Key", System.getenv("IMAGEPIPELINE_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
{
  "input_image": "https://.../photo.webp",
  "prompt": "caucasian woman with green eyes"
}
"""))
    .build();
HttpResponse<String> res = client.send(req, BodyHandlers.ofString());

Field	Type	Default	Notes
input_image	string	,	Required. Public URL of the image to edit.
prompt	string	,	Required. Describe the new person.
use_segmentation	boolean	true	When true, only skin and hair are edited; clothing is kept.
tone_correction	number	,	Colour correction strength after editing (0.0 to 1.0).
seed	integer	-1	-1 randomizes; set a value for reproducibility.
palette	string[]	,	Brand colours as hex codes.
output_format	string	webp	webp, jpeg, or png.
profile_id	string	,	Apply an identity profile.
callback_url	string	,	Webhook URL on completion.

Response — poll GET …/status/{job_id} until status is completed:

{
  "job_id": "job_a1c7b305",
  "status": "completed",
  "result_url": "https://cdn.imagepipeline.io/o/a1c7b305.webp",
  "processing_time_seconds": 33.0,
  "balance_remaining_usd": 187.52
}

Instamodel

POST /creator/instamodel/image/v1, generate social-ready model shots from a single input_face and a prompt.

cURL

curl -X POST https://api.imagepipeline.io/creator/instamodel/image/v1 \
  -H "X-API-Key: $IMAGEPIPELINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input_face": "https://.../face.webp",
  "prompt": "streetwear lookbook, urban backdrop"
}'

JavaScript

const res = await fetch("https://api.imagepipeline.io/creator/instamodel/image/v1", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.IMAGEPIPELINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "input_face": "https://.../face.webp",
  "prompt": "streetwear lookbook, urban backdrop"
}),
});
const { job_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.imagepipeline.io/creator/instamodel/image/v1",
    headers={"X-API-Key": API_KEY},
    json={
  "input_face": "https://.../face.webp",
  "prompt": "streetwear lookbook, urban backdrop"
},
)
job_id = res.json()["job_id"]

Java

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.imagepipeline.io/creator/instamodel/image/v1"))
    .header("X-API-Key", System.getenv("IMAGEPIPELINE_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
{
  "input_face": "https://.../face.webp",
  "prompt": "streetwear lookbook, urban backdrop"
}
"""))
    .build();
HttpResponse<String> res = client.send(req, BodyHandlers.ofString());

Field	Type	Default	Notes
prompt	string	,	Required. Describe the scene, outfit, or style.
input_face	string	,	Required. Public URL of the input face image.
width / height	integer	768 / 1024	Output dimensions (max 2048).
negative_prompt	string	,	Negative prompt applied to the generation.
seed	integer	,	Seed for reproducibility (omit for random).
palette	string[]	,	Brand colours as hex codes.
output_format	string	webp	webp, jpeg, or png.
profile_id	string	,	Apply an identity profile.
callback_url	string	,	Webhook URL on completion.
server_id	string	,	Enterprise: pin to a dedicated pod.

Response — poll GET …/status/{job_id} until status is completed:

{
  "job_id": "job_b6e0f249",
  "status": "completed",
  "result_url": "https://cdn.imagepipeline.io/o/b6e0f249.webp",
  "processing_time_seconds": 29.7,
  "balance_remaining_usd": 187.52
}

Virtual Try-On

POST /creator/tryon/image/v1, dress a person_image in a clothing_image.

cURL

curl -X POST https://api.imagepipeline.io/creator/tryon/image/v1 \
  -H "X-API-Key: $IMAGEPIPELINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "person_image": "https://.../person.webp",
  "clothing_image": "https://.../jacket.webp",
  "gender": "woman",
  "clothing_type": "denim jacket"
}'

JavaScript

const res = await fetch("https://api.imagepipeline.io/creator/tryon/image/v1", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.IMAGEPIPELINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "person_image": "https://.../person.webp",
  "clothing_image": "https://.../jacket.webp",
  "gender": "woman",
  "clothing_type": "denim jacket"
}),
});
const { job_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.imagepipeline.io/creator/tryon/image/v1",
    headers={"X-API-Key": API_KEY},
    json={
  "person_image": "https://.../person.webp",
  "clothing_image": "https://.../jacket.webp",
  "gender": "woman",
  "clothing_type": "denim jacket"
},
)
job_id = res.json()["job_id"]

Java

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.imagepipeline.io/creator/tryon/image/v1"))
    .header("X-API-Key", System.getenv("IMAGEPIPELINE_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
{
  "person_image": "https://.../person.webp",
  "clothing_image": "https://.../jacket.webp",
  "gender": "woman",
  "clothing_type": "denim jacket"
}
"""))
    .build();
HttpResponse<String> res = client.send(req, BodyHandlers.ofString());

Field	Type	Default	Notes
person_image	string	,	Required. Public URL of the person/model image.
clothing_image	string	,	Required. Public URL of the clothing item.
gender	string	,	Required. man or woman.
clothing_type	string	,	Required. Type of clothing; be specific for best results.
width / height	integer	person image	Output dimensions (256 to 2048).
use_segmentation	boolean	false	When false, edits the full image and colour-corrects.
tone_correction	number	,	Colour correction strength (0.0 to 1.0).
seed	integer	-1	-1 randomizes; set a value for reproducibility.
output_format	string	webp	webp, jpeg, or png.
profile_id	string	,	Apply an identity profile.
callback_url	string	,	Webhook URL on completion.

Response — poll GET …/status/{job_id} until status is completed:

{
  "job_id": "job_3f72d8e5",
  "status": "completed",
  "result_url": "https://cdn.imagepipeline.io/o/3f72d8e5.webp",
  "processing_time_seconds": 44.0,
  "balance_remaining_usd": 187.52
}

Voice Clone

POST /identity/voice/clone/v1, clone a voice from reference_voice_url and speak text. Outputs are watermarked by default.

cURL

curl -X POST https://api.imagepipeline.io/identity/voice/clone/v1 \
  -H "X-API-Key: $IMAGEPIPELINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Hello from my cloned voice.",
  "reference_voice_url": "https://.../sample.wav"
}'

JavaScript

const res = await fetch("https://api.imagepipeline.io/identity/voice/clone/v1", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.IMAGEPIPELINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "text": "Hello from my cloned voice.",
  "reference_voice_url": "https://.../sample.wav"
}),
});
const { job_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.imagepipeline.io/identity/voice/clone/v1",
    headers={"X-API-Key": API_KEY},
    json={
  "text": "Hello from my cloned voice.",
  "reference_voice_url": "https://.../sample.wav"
},
)
job_id = res.json()["job_id"]

Java

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.imagepipeline.io/identity/voice/clone/v1"))
    .header("X-API-Key", System.getenv("IMAGEPIPELINE_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
{
  "text": "Hello from my cloned voice.",
  "reference_voice_url": "https://.../sample.wav"
}
"""))
    .build();
HttpResponse<String> res = client.send(req, BodyHandlers.ofString());

Field	Type	Default	Notes
text	string	,	Required. Text to synthesise with the cloned voice.
reference_voice_url	string	,	Required. Public URL of the reference voice audio (WAV).
language_id	string	en	Language code, e.g. en, zh, ja, ko, he.
max_new_tokens	integer	256	Maximum tokens to generate.
exaggeration	number	0.5	Expressiveness (0.0 neutral to 1.0 maximum).
apply_watermark	boolean	true	Embed an inaudible audio watermark (recommended).
callback_url	string	,	Webhook URL on completion.
server_id	string	,	Enterprise: pin to a dedicated pod.

Response — poll GET …/status/{job_id} until status is completed:

{
  "job_id": "job_c50a91d7",
  "status": "completed",
  "result_url": "https://cdn.imagepipeline.io/o/c50a91d7.wav",
  "processing_time_seconds": 6.3,
  "balance_remaining_usd": 187.52
}