Python SDK

The official Python client, imagepipeline on PyPI. Parameters below are generated from the live API spec.

Install

pip install imagepipeline

Requires Python 3.9+.

Initialize

Grab an API key from the dashboard, see Authentication.

from imagepipeline import ImagePipeline

ip = ImagePipeline("ip_live_xxxxxxxxxxxx")

Quick examples

# Generate
result = ip.generate.image(prompt="fashion model, white studio background, editorial lighting")
print(result.url)

# Virtual try-on
result = ip.identity.tryon(
    person_image="https://cdn.example.com/model.jpg",
    clothing_image="https://cdn.example.com/shirt.jpg",
    gender="woman",
)
print(result.url)

Async and webhooks

Every compute method blocks and polls by default. Pass wait=False to get a job id back immediately, or pass callback_url to receive a webhook when the job completes. See Jobs & Webhooks.

job = ip.generate.image(prompt="...", wait=False)
print(job.job_id)

Parameter reference

Snake_case keyword arguments per method. Every compute method also accepts wait (default True). Profiles also expose list_profiles(), get_profile(profile_id), and delete_profile(profile_id).

Generate

Generate image

ip.generate.image(...) · POST /generate/image/v1

Parameter	Type	Default	Description
prompt	string	-	Required. Text prompt describing the image to generate.
height	integer	1024	Output height in pixels (max 1024).
width	integer	1024	Output width in pixels (max 1024).
num_inference_steps	integer	-	Number of denoising steps. Default 8
guidance_scale	number	-	Guidance scale. Omit to use the model default (0.0 for Z-Image Turbo).
seed	integer	-1	Seed for reproducibility. -1 = random.
enhance_prompt	boolean	false	Run the prompt through a lightweight AI enhancer before generation. Expands terse prompts into detailed visual descriptions - useful for short or abstract inputs. Adds ~1-2 s. Default false.
logo_url	string	-	Public URL of your company logo (PNG or WebP with transparency recommended). Stamped at bottom-right at 50% opacity.
output_format	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
callback_url	string	-	Optional webhook URL. When the job completes or fails we POST a WebhookEvent object to this URL. See the WebhookEvent schema (Webhooks section) for the exact payload shape. result_url in the payload is temporary (∼24 h) - download the file immediately.
profile_id	string	-	Identity profile ID from /profiles/v1. When provided, the profile's prompt_template and quality settings are applied automatically - keeping theme and brand context consistent across a generation chain.
server_id	string	-	Enterprise: pod ID to pin this request to a specific dedicated pod.

Generate video

ip.generate.video(...) · POST /generate/video/v1

Parameter	Type	Default	Description
input_image	string	-	Required. Public URL of the image to animate.
prompt	string	"make this image come alive, cinematic motion, smooth animation"	Describe the animation style or motion. Defaults to cinematic motion.
height	integer	512	Output height in pixels (max 1536, must be divisible by 32).
width	integer	896	Output width in pixels (max 1536, must be divisible by 32).
duration_seconds	number	2	Video duration in seconds (0.1-10.0).
seed	integer	42	Seed for reproducibility.
callback_url	string	-	Optional webhook URL. When the job completes or fails we POST a WebhookEvent object to this URL. See the WebhookEvent schema (Webhooks section) for the exact payload shape. result_url in the payload is temporary (∼24 h) - download the file immediately.
server_id	string	-	Enterprise: pod ID to pin this request to a specific dedicated pod.

Generate speech

ip.generate.speech(...) · POST /generate/speech/v1

Parameter	Type	Default	Description
text	string	-	Required. Text to convert to speech.
language_id	string	"en"	Language code (e.g. en, zh, ja, ko, he).
target_voice_path	string	-	Public URL of a reference voice audio file for voice cloning (WAV/MP3, 5-30 s recommended). Required for /identity/voice/clone. If omitted on /generate/speech, a default voice is used.
max_new_tokens	integer	256	Maximum tokens to generate.
exaggeration	number	0.5	Expressiveness level (0.0 = neutral, 1.0 = maximum).
apply_watermark	boolean	true	Embed an inaudible audio watermark in the output (recommended for compliance).
callback_url	string	-	Optional webhook URL. When the job completes or fails we POST a WebhookEvent object to this URL. See the WebhookEvent schema (Webhooks section) for the exact payload shape. result_url in the payload is temporary (∼24 h) - download the file immediately.
server_id	string	-	Enterprise: pod ID to pin this request to a specific dedicated pod.

Generate 3D

ip.generate.generate_3d(...) · POST /generate/3d/v1

Parameter	Type	Default	Description
image_path	string	-	Required. Public URL or path of the input image to convert to 3D.
mode	string	"generate"	Generation mode: generate (mesh only), paint (texture an existing mesh), or generate_and_paint (mesh + textures in one pass).
mesh_save_name	string	-	Optional filename for the output mesh (e.g. model.obj).
painted_save_name	string	-	Optional filename for the textured/painted mesh.
auto_unload	boolean	true	Unload the generation pipeline from GPU after completion to free memory.
callback_url	string	-	Optional webhook URL. When the job completes or fails we POST a WebhookEvent object to this URL. See the WebhookEvent schema (Webhooks section) for the exact payload shape. result_url in the payload is temporary (∼24 h) - download the file immediately.
server_id	string	-	Enterprise: pod ID to pin this request to a specific dedicated pod.

Edit

Edit image

ip.edit.image(...) · POST /edit/image/v1

Parameter	Type	Default	Description
input_image	string or array<string>	-	Image(s) to edit. Pass a single URL string, or an array of URL strings to provide multiple reference images (e.g. two subjects to combine).
prompt	string	-	Required. Instruction describing the edits to apply.
mode	string	-	Processing mode. Use anime to convert a photo to an illustrated/anime style.
output_format	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
palette	array<string>	-	Brand colour palette as hex codes (e.g. ['#FF5733']). Blended into the output.
num_inference_steps	integer	-	Number of diffusion steps (1-100). Higher = better quality but slower. Default: 8.
guidance_scale	number	-	Classifier-free guidance scale (0.0-20.0). Set to 0 to disable CFG (distilled/Lightning models). Default: 1.5.
seed	integer	-1	Seed for reproducibility. -1 = random.
callback_url	string	-	Optional webhook URL. When the job completes or fails we POST a WebhookEvent object to this URL. See the WebhookEvent schema (Webhooks section) for the exact payload shape. result_url in the payload is temporary (∼24 h) - download the file immediately.
profile_id	string	-	Identity profile ID from /profiles/v1. When provided, the profile's prompt_template, quality settings, and brand palette are applied automatically - keeping theme and brand context consistent across an editing chain.
refine_strength	number	-	Z-Image Turbo refinement pass after editing (0.0-1.0). At 0.25-0.40, preserves composition from the edit step while improving skin photorealism and texture detail. Omit or set to 0 to skip the refinement pass.
faster_inference	boolean	true	When true (default), uses the Lightning LoRA distillation for fast 8-step inference. Set to false for higher-quality 20-step inference without distillation - slower but preserves finer product and skin details.
cfg_norm_strength	number	-	CFG normalization strength (0.0-1.0). Rescales the guided prediction to match the magnitude of the conditioned-only prediction, preventing colour saturation and tone shifts caused by high true_cfg_scale. Try 0.5-0.8 when colours look oversaturated. 0 (default) disables it.
product_saturation	number	-	Saturation multiplier applied to the product image (image 2) before editing. 0.0 = greyscale, 1.0 = unchanged, <1.0 desaturates (e.g. 0.85 reduces colour shift). Omit to use the server default (0.85).
tone_correction	number	-	Post-edit tonal correction strength (0.0-1.0). Corrects colour drift that diffusion models introduce in edited regions - blends the colour profile of the edited area toward the original image. 0.0 disables it, 1.0 is full correction. Default: 0.6. Lower values (0.3-0.5) preserve more of the model's generated colour.
has_text	boolean	-	Whether the image contains visible text, logos, or labels. When false, text detection (EasyOCR) is skipped - saves ~2-3 s if your image has no text. When true or omitted, text regions are auto-detected and preserved during background changes. Only applies to bg_change edits.
has_product	boolean	-	Whether the image contains a physical product as the main subject. Passed to the worker for routing and analytics. Does not affect mask logic.
server_id	string	-	Enterprise: pod ID to pin this request to a specific dedicated pod.

Background

Change background

ip.background.change(...) · POST /background/change/image/v1

Parameter	Type	Default	Description
input_image	string	-	Required. Public URL of the image whose background will be replaced.
prompt	string	-	Required. Describe the new background - e.g. beach at sunset, white studio background, forest path in autumn.
use_segmentation	boolean	true	When true (default), the subject is isolated and composited back over the generated background - preserves subject edges cleanly. When false, the full image edit is used with colour correction.
tone_correction	number	-	Colour correction strength (0.0-1.0). Blends the edited background's colour profile toward the original to reduce drift. Default: 0.6.
subject_description	string	-	Required. Short description of the main subject to preserve - e.g. protein powder tub, glass bottle, sneakers, person. Helps the segmentation model identify exactly what to keep.
has_text	boolean	-	Whether the image contains visible text or labels. Set to false to skip text detection and save ~2-3 s. Omit to auto-detect.
palette	array<string>	-	Brand colour palette as hex codes. Blended into the output.
num_inference_steps	integer	-	Number of diffusion steps. Default: 8. Higher = more detail, slower.
true_cfg_scale	number	-	CFG scale. Default: 4.0.
faster_inference	boolean	-	Enable faster inference mode. Default: true.
output_format	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
harmonize_strength	number	-	Lighting harmonization strength (0.0-1.0). When set, the subject's low-frequency lighting and colour cast are shifted to match the generated background (frequency-separated relight: high-frequency texture/labels stay from the original). 0.7 is a good starting point. Omit or 0 to disable (default).
seed	integer	-1	Seed for reproducibility. -1 = random.
callback_url	string	-	Webhook URL. When the job completes or fails we POST a WebhookEvent to this URL. result_url is temporary (~24 h) - download the file promptly.

Remove background

ip.background.remove(...) · POST /background/remove/image/v1

Parameter	Type	Default	Description
input_image	string	-	Required. Public URL of the image to process.
recolor	string	-	Hex color to use as the new background, e.g. #FFFFFF or F0F0F0. When omitted, only the transparent cutout is returned.
drop_shadow	boolean	false	Add a soft drop shadow beneath the subject before compositing.
shadow_opacity	number	0.38	Shadow darkness 0-1.
shadow_blur	number	0.018	Blur radius as fraction of image width.
shadow_dy	number	0.022	Vertical shadow offset as fraction of height.
shadow_dx	number	0.004	Horizontal shadow offset as fraction of width.
output_format	string	"png"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
callback_url	string	-	Optional webhook URL. A WebhookEvent is POSTed when the job completes or fails. result_url in the payload is temporary (∼24 h) - download immediately.

Upscale

Upscale image

ip.upscale.image(...) · POST /upscale/image/v1

Parameter	Type	Default	Description
input_image	string	-	Required. Public URL of the image to upscale and enhance.
scale	integer	4	Upscale factor: 1 (enhance only), 2, 3, or 4. Default: 4.
output_format	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
callback_url	string	-	Optional webhook URL. When the job completes or fails we POST a WebhookEvent object to this URL. See the WebhookEvent schema (Webhooks section) for the exact payload shape. result_url in the payload is temporary (∼24 h) - download the file immediately.
server_id	string	-	Enterprise: pod ID to pin this request to a specific dedicated pod.

Branding

Logo placement

ip.branding.logo(...) · POST /branding/logo/image/v1

Parameter	Type	Default	Description
input_image	string	-	Required. Public URL of the base image to stamp the logo onto.
logo_url	string	-	Required. Public URL of your logo (PNG with transparency recommended). Stamped at the chosen corner at 50% opacity.
position	string	"bottom_right"	Corner to place the logo stamp. Default: bottom_right. One of: bottom_right, bottom_left, top_right, top_left.
output_format	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
callback_url	string	-	Webhook URL. When the job completes or fails we POST a WebhookEvent to this URL. result_url is temporary (~24 h) - download the file promptly.

Branded template

ip.branding.template(...) · POST /branding/template/image/v1

Parameter	Type	Default	Description
input_image	string	-	Required. Public URL of your model or product photo. The brand palette is extracted automatically from the clothing and accessories.
background_prompt	string	"clean professional studio background"	Describe the background scene - e.g. urban rooftop at dusk, minimal white studio, lush botanical garden. The derived palette colors are automatically injected into this prompt.
palette_mode	string	"similar"	How the background palette relates to the outfit colors: - similar - same hue family, harmonious and safe - complementary - opposite on the color wheel, classic contrast - radical - triadic shift with boosted saturation, bold and eye-catching One of: similar, complementary, radical.
subject_description	string	-	Short description of the subject to preserve - e.g. woman in red dress, sneaker, glass bottle. Helps the segmentation model identify what to keep.
logo_url	string	-	Public URL of your logo (PNG with transparency recommended). Stamped at the chosen corner at 50% opacity after background generation.
position	string	"bottom_right"	Corner for the logo stamp. Default: bottom_right. One of: bottom_right, bottom_left, top_right, top_left.
output_format	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
seed	integer	-1	Seed for reproducibility. -1 = random.
callback_url	string	-	Webhook URL. When the job completes or fails we POST a WebhookEvent to this URL. result_url is temporary (~24 h) - download the file promptly.

Identity & Creator

Virtual try-on

ip.identity.tryon(...) · POST /creator/tryon/image/v1

Parameter	Type	Default	Description
person_image	string	-	Required. Public URL of the person/model image (the body to dress).
clothing_image	string	-	Required. Public URL of the clothing item to place on the person.
gender	string	-	Required. Gender of the person (man or woman). One of: man, woman.
clothing_type	string	-	Required. Type of clothing shown in clothing_image. Be specific for best results - e.g. jacket, dress, blazer, jeans, shirt, skirt.
width	integer	-	Output width in pixels (256-2048). Defaults to the person image's native width (capped at 2048 and rounded to 16). For clothing try-on, portrait dimensions (e.g. 832 × 1248) give the best results.
height	integer	-	Output height in pixels (256-2048). Defaults to the person image's native height (capped at 2048 and rounded to 16). For clothing try-on, portrait dimensions (e.g. 832 × 1248) give the best results.
output_format	string	"png"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
seed	integer	-1	Seed for reproducibility. -1 = random.
garment_region	string	"upper"	Which part of the body the garment covers. Controls the region where colour correction is applied so other clothing isn't affected. upper (default) - jacket, shirt, blazer, top. lower - pants, jeans, skirt, shorts. full - dress, jumpsuit, suit (whole body). One of: upper, lower, full.
tone_correction	number	-	Colour correction strength (0.0-1.0). Controls how closely the generated garment's colour is matched to the reference image. Default: 0.4. Lower values (0.2) preserve the AI's interpretation; higher values (0.6) pull the colour tighter to the clothing reference.
profile_id	string	-	Identity profile ID from /profiles/v1. Applies stored settings automatically.
callback_url	string	-	Webhook URL. When the job completes or fails we POST a WebhookEvent to this URL. result_url in the payload is temporary (~24 h) - download the file promptly.

Face swap

ip.identity.faceswap(...) · POST /identity/faceswap/image/v1

Parameter	Type	Default	Description
target	string	-	Required. Public URL of the target image (the body/scene where the face will appear).
source	string	-	Required. Public URL of the source face image (the face to swap in).
upscale	number	1.5	Output upscale factor (1.0-4.0).
restore_weight	number	0.5	Face restoration strength (0.0-1.0). Higher = sharper face detail.
output_format	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
profile_id	string	-	Identity profile ID from /identity/profiles/v1. When provided, the profile's settings are applied automatically.
callback_url	string	-	Optional webhook URL. When the job completes or fails we POST a WebhookEvent object to this URL. See the WebhookEvent schema (Webhooks section) for the exact payload shape. result_url in the payload is temporary (∼24 h) - download the file immediately.
server_id	string	-	Enterprise: pod ID to pin this request to a specific dedicated pod.

Identity lock

ip.identity.lock(...) · POST /identity/lock/image/v1

Parameter	Type	Default	Description
input_image	string	-	Required. Public URL of the source image whose identity will be locked and preserved.
prompt	string	-	Required. Describe the desired scene or appearance changes. The person's identity is automatically preserved throughout.
height	integer	1024	Output height in pixels (max 2048).
width	integer	1024	Output width in pixels (max 2048).
output_format	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
palette	array<string>	-	Brand colour palette as hex codes. Blended into the output.
negative_prompt	string	-	Negative prompt. Activates classifier-free guidance when set.
num_inference_steps	integer	-	Number of diffusion steps (1-100). Higher = better quality but slower. Default: 8.
guidance_scale	number	-	Classifier-free guidance scale (1.0-20.0). Higher = follows prompt more strictly. Default: 1.5.
seed	integer	-1	Seed for reproducibility. -1 = random.
profile_id	string	-	Identity profile ID from /identity/profiles/v1. When provided, the profile's settings override manual generation params.
callback_url	string	-	Optional webhook URL. When the job completes or fails we POST a WebhookEvent object to this URL. See the WebhookEvent schema (Webhooks section) for the exact payload shape. result_url in the payload is temporary (∼24 h) - download the file immediately.
server_id	string	-	Enterprise: pod ID to pin this request to a specific dedicated pod.

Identity replace

ip.identity.replace(...) · POST /identity/replace/image/v1

Parameter	Type	Default	Description
input_image	string	-	Required. Public URL of the image whose identity will be replaced.
prompt	string	-	Required. Describe the new person - e.g. caucasian woman with green eyes, 30-year-old man with short dark hair and a beard. The server constructs the full edit instruction from this description.
use_segmentation	boolean	true	When true (default), only skin and hair are edited; clothing, background, and text are preserved from the original via masking and compositing. When false, the edit applies to the full image with colour correction scoped to the non-skin/hair region.
tone_correction	number	-	Colour correction strength after editing (0.0-1.0). Corrects colour drift in the edited region toward the original image. Default: 0.6. Set to 0.0 to disable.
output_format	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
seed	integer	-1	Seed for reproducibility. -1 = random.
palette	array<string>	-	Brand colour palette as hex codes. Blended into the output.
profile_id	string	-	Identity profile ID from /profiles/v1. Applies stored settings automatically.
callback_url	string	-	Webhook URL. When the job completes or fails we POST a WebhookEvent to this URL. result_url is temporary (~24 h) - download the file promptly.

Instamodel

ip.identity.instamodel(...) · POST /creator/instamodel/image/v1

Parameter	Type	Default	Description
prompt	string	-	Required. Describe the scene, outfit, or style for the generated image.
input_face	string	-	Required. Public URL of the input face image.
height	integer	1024	Output height in pixels (max 2048).
width	integer	768	Output width in pixels (max 2048).
seed	integer	-	Seed for reproducibility (omit for random).
negative_prompt	string	-	Negative prompt applied to the generation.
output_format	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
profile_id	string	-	Identity profile ID from /profiles/v1. When provided, the profile's settings are applied automatically.
callback_url	string	-	Optional webhook URL. When the job completes or fails we POST a WebhookEvent object to this URL. See the WebhookEvent schema (Webhooks section) for the exact payload shape. result_url in the payload is temporary (~24 h) - download the file immediately.
server_id	string	-	Enterprise: pod ID to pin this request to a specific dedicated pod.

Voice clone

ip.identity.voice_clone(...) · POST /identity/voice/clone/v1

Parameter	Type	Default	Description
text	string	-	Required. Text to synthesise with the cloned voice.
reference_voice_url	string	-	Required. Public URL of the reference voice audio file for cloning (WAV or MP3, 5-30 s recommended).
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 level (0.0 = neutral, 1.0 = maximum).
apply_watermark	boolean	true	Embed an inaudible audio watermark in the output (recommended for compliance).
callback_url	string	-	Optional webhook URL. When the job completes or fails we POST a WebhookEvent object to this URL. See the WebhookEvent schema (Webhooks section) for the exact payload shape. result_url in the payload is temporary (∼24 h) - download the file immediately.
server_id	string	-	Enterprise: pod ID to pin this request to a specific dedicated pod.

Profiles

Create identity profile

ip.identity.create_profile(...) · POST /profiles/v1

Parameter	Type	Default	Description
name	string	-	Required. Human-readable name for this profile, e.g. 'Anna - summer campaign'.
description	string	-	Optional notes about this identity profile.
tags	array<string>	-	Optional tags for filtering, e.g. ['influencer', 'campaign-2026'].
callback_url	string	-	Default webhook URL for job completion events from this profile. Overridable per-request.
intent_id	string	-	Optimise this profile for a specific intent, e.g. 'identity_lock'.
prompt_template	string	-	Custom Jinja2 prompt template for this profile. Use {{user_prompt}} to inject the caller's prompt. Example: 'Portrait of Anna, {{user_prompt}}, consistent lighting'.
negative_prompt	string	-	Negative prompt applied to every job using this profile.
steps	integer	-	-
cfg_scale	number	-	-
seed_strategy	string	"random"	'random' - new seed per job; 'fixed' - always use fixed_seed; 'user' - honour per-request seed if provided.
fixed_seed	integer	-	Seed to use when seed_strategy='fixed'. Ignored for other strategies.
palette	array<string>	-	Brand color palette as hex codes applied to all jobs from this profile (e.g. ['#FF5733', '#3498DB']).
height	integer	-	Default output image height.
width	integer	-	Default output image width.
output_format	string	-	Default output format: 'webp', 'jpeg', or 'png'. Use 'png' for editing chains; 'webp' for final app delivery.
prompt_template_mode	string	"suffix"	How to combine the profile's prompt_template with the caller's prompt. 'suffix' (default) appends the template after the user prompt; 'prefix' prepends it before.
extra_params	object	-	Additional model-specific parameters passed through to the worker.

Upload

Upload image

ip.upload.image(...) · POST /upload/image/v1

Pass a local file path (or file object). Returns a hosted url you can feed into any other method.

Parameter	Type	Default	Description
file	string	-	Required. Image file to upload (PNG, JPEG, WebP, GIF - max 20 MB).