TypeScript SDK

The official JavaScript / TypeScript client, @imagepipeline/sdk on npm. Fully typed. Parameters below are generated from the live API spec.

Install

npm install @imagepipeline/sdk
# or
pnpm add @imagepipeline/sdk
# or
yarn add @imagepipeline/sdk

Requires Node.js 18+ (uses native fetch).

Initialize

Grab an API key from the dashboard, see Authentication.

import { ImagePipeline } from "@imagepipeline/sdk";

const ip = new ImagePipeline("ip_live_xxxxxxxxxxxx");

Quick examples

// Generate
const result = await ip.generate.image({
  prompt: "fashion model, white studio background, editorial lighting",
});
console.log(result.url);

// Virtual try-on
const tryon = await ip.identity.tryon({
  personImage: "https://cdn.example.com/model.jpg",
  clothingImage: "https://cdn.example.com/shirt.jpg",
  gender: "woman",
});
console.log(tryon.url);

Async and webhooks

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

const job = await ip.generate.image({ prompt: "...", wait: false });
console.log(job.jobId);

Parameter reference

camelCase options object per method. Every compute method also accepts wait (default true). Profiles also expose listProfiles(), getProfile(profileId), and deleteProfile(profileId).

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).
numInferenceSteps	integer	-	Number of denoising steps. Default 8
guidanceScale	number	-	Guidance scale. Omit to use the model default (0.0 for Z-Image Turbo).
seed	integer	-1	Seed for reproducibility. -1 = random.
enhancePrompt	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.
logoUrl	string	-	Public URL of your company logo (PNG or WebP with transparency recommended). Stamped at bottom-right at 50% opacity.
outputFormat	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
callbackUrl	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.
profileId	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.
serverId	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
inputImage	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).
durationSeconds	number	2	Video duration in seconds (0.1-10.0).
seed	integer	42	Seed for reproducibility.
callbackUrl	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.
serverId	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.
languageId	string	"en"	Language code (e.g. en, zh, ja, ko, he).
targetVoicePath	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.
maxNewTokens	integer	256	Maximum tokens to generate.
exaggeration	number	0.5	Expressiveness level (0.0 = neutral, 1.0 = maximum).
applyWatermark	boolean	true	Embed an inaudible audio watermark in the output (recommended for compliance).
callbackUrl	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.
serverId	string	-	Enterprise: pod ID to pin this request to a specific dedicated pod.

Generate 3D

ip.generate.generate3d({ ... }) · POST /generate/3d/v1

Parameter	Type	Default	Description
imagePath	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).
meshSaveName	string	-	Optional filename for the output mesh (e.g. model.obj).
paintedSaveName	string	-	Optional filename for the textured/painted mesh.
autoUnload	boolean	true	Unload the generation pipeline from GPU after completion to free memory.
callbackUrl	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.
serverId	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
inputImage	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.
outputFormat	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.
numInferenceSteps	integer	-	Number of diffusion steps (1-100). Higher = better quality but slower. Default: 8.
guidanceScale	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.
callbackUrl	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.
profileId	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.
refineStrength	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.
fasterInference	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.
cfgNormStrength	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.
productSaturation	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).
toneCorrection	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.
hasText	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.
hasProduct	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.
serverId	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
inputImage	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.
useSegmentation	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.
toneCorrection	number	-	Colour correction strength (0.0-1.0). Blends the edited background's colour profile toward the original to reduce drift. Default: 0.6.
subjectDescription	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.
hasText	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.
numInferenceSteps	integer	-	Number of diffusion steps. Default: 8. Higher = more detail, slower.
trueCfgScale	number	-	CFG scale. Default: 4.0.
fasterInference	boolean	-	Enable faster inference mode. Default: true.
outputFormat	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
harmonizeStrength	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.
callbackUrl	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
inputImage	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.
dropShadow	boolean	false	Add a soft drop shadow beneath the subject before compositing.
shadowOpacity	number	0.38	Shadow darkness 0-1.
shadowBlur	number	0.018	Blur radius as fraction of image width.
shadowDy	number	0.022	Vertical shadow offset as fraction of height.
shadowDx	number	0.004	Horizontal shadow offset as fraction of width.
outputFormat	string	"png"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
callbackUrl	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
inputImage	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.
outputFormat	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
callbackUrl	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.
serverId	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
inputImage	string	-	Required. Public URL of the base image to stamp the logo onto.
logoUrl	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.
outputFormat	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
callbackUrl	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
inputImage	string	-	Required. Public URL of your model or product photo. The brand palette is extracted automatically from the clothing and accessories.
backgroundPrompt	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.
paletteMode	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.
subjectDescription	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.
logoUrl	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.
outputFormat	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
seed	integer	-1	Seed for reproducibility. -1 = random.
callbackUrl	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
personImage	string	-	Required. Public URL of the person/model image (the body to dress).
clothingImage	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.
clothingType	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.
outputFormat	string	"png"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
seed	integer	-1	Seed for reproducibility. -1 = random.
garmentRegion	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.
toneCorrection	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.
profileId	string	-	Identity profile ID from /profiles/v1. Applies stored settings automatically.
callbackUrl	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).
restoreWeight	number	0.5	Face restoration strength (0.0-1.0). Higher = sharper face detail.
outputFormat	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
profileId	string	-	Identity profile ID from /identity/profiles/v1. When provided, the profile's settings are applied automatically.
callbackUrl	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.
serverId	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
inputImage	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).
outputFormat	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.
negativePrompt	string	-	Negative prompt. Activates classifier-free guidance when set.
numInferenceSteps	integer	-	Number of diffusion steps (1-100). Higher = better quality but slower. Default: 8.
guidanceScale	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.
profileId	string	-	Identity profile ID from /identity/profiles/v1. When provided, the profile's settings override manual generation params.
callbackUrl	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.
serverId	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
inputImage	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.
useSegmentation	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.
toneCorrection	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.
outputFormat	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.
profileId	string	-	Identity profile ID from /profiles/v1. Applies stored settings automatically.
callbackUrl	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.
inputFace	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).
negativePrompt	string	-	Negative prompt applied to the generation.
outputFormat	string	"webp"	Output image format. Applies to all image-producing endpoints. One of: webp, jpeg, png.
profileId	string	-	Identity profile ID from /profiles/v1. When provided, the profile's settings are applied automatically.
callbackUrl	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.
serverId	string	-	Enterprise: pod ID to pin this request to a specific dedicated pod.

Voice clone

ip.identity.voiceClone({ ... }) · POST /identity/voice/clone/v1

Parameter	Type	Default	Description
text	string	-	Required. Text to synthesise with the cloned voice.
referenceVoiceUrl	string	-	Required. Public URL of the reference voice audio file for cloning (WAV or MP3, 5-30 s recommended).
languageId	string	"en"	Language code (e.g. en, zh, ja, ko, he).
maxNewTokens	integer	256	Maximum tokens to generate.
exaggeration	number	0.5	Expressiveness level (0.0 = neutral, 1.0 = maximum).
applyWatermark	boolean	true	Embed an inaudible audio watermark in the output (recommended for compliance).
callbackUrl	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.
serverId	string	-	Enterprise: pod ID to pin this request to a specific dedicated pod.

Profiles

Create identity profile

ip.identity.createProfile({ ... }) · 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'].
callbackUrl	string	-	Default webhook URL for job completion events from this profile. Overridable per-request.
intentId	string	-	Optimise this profile for a specific intent, e.g. 'identity_lock'.
promptTemplate	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'.
negativePrompt	string	-	Negative prompt applied to every job using this profile.
steps	integer	-	-
cfgScale	number	-	-
seedStrategy	string	"random"	'random' - new seed per job; 'fixed' - always use fixed_seed; 'user' - honour per-request seed if provided.
fixedSeed	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.
outputFormat	string	-	Default output format: 'webp', 'jpeg', or 'png'. Use 'png' for editing chains; 'webp' for final app delivery.
promptTemplateMode	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.
extraParams	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).