Studio

Edit

Edit images based on a text prompt.

Provide input images (base64 or public URL) and a prompt describing the desired edit. Returns base64 images or signed download URLs.

post/v2/phota/edit

Request

Base URL
https://api.photalabs.com
Auth
API key in header X-API-Key

Request body

asyncboolean

Submit asynchronously. Returns 202 with a job_id to poll at GET /v1/jobs/{job_id} instead of holding the connection until the image is ready.

callback_urlstring nullable

Optional https URL we POST the signed result to on completion. Best-effort (polling remains authoritative). Requires async=true.

client_request_idstring nullable

Idempotency key. A retried submit with the same value returns the original job instead of creating (and charging for) a new one.

response_mode'bytes' | 'urls'

Response delivery mode. 'bytes': return base64-encoded image data (default). 'urls': return signed download URLs (24-hour expiry) instead of image bytes.

promptstring

Text prompt describing the desired edit.

imagesstring[]

Input images as raw base64 strings or publicly accessible URLs. Both formats are auto-detected. Supported formats: JPEG, PNG, WebP, and HEIC/HEIF. Images larger than 4K (4096px) are automatically resized; for best results, provide images at 4K or below.

profile_idsstring[]

Subset of your account's profiles relevant to this request. Your account holds all profiles, but only pass the ones belonging to the end-user whose photo is being edited. These profiles serve as candidates for identity preservation. The fewer profiles you pass, the easier it is for our system to determine which profiles are relevant.

num_output_imagesinteger

Number of output images to generate (1-4).

aspect_ratio'auto' | '1:1' | '3:4' | '4:3' | '9:16' | '16:9' nullable

Output aspect ratio (1:1, 3:4, 4:3, 9:16, 16:9; 'auto' matches the input image where supported). Omit to use the model's default: 'auto' for models that support it, '4:3' otherwise. 'auto' is rejected with 400 for models that do not support it.

resolution'1K' | '2K' | '4K'

Output resolution (1K, 2K, 4K). Per-model support varies; see /models.

Quality tier (auto, low, medium, high; xhigh and max on GPT Image 2.5 only). Only supported by the GPT Image models (gpt-image-2, gpt-image-2.5-sunburst, gpt-image-2.5-flare); passing this field for other models returns 400. Omit (or pass 'auto') to let the provider pick — on the GPT Image models this resolves to OpenAI's auto tier. Lower tiers reduce output tokens and therefore settled cost.

custom_resolutionstring nullable

Exact GPT Image output size as WIDTHxHEIGHT, e.g. 1536x864. Edges must be multiples of 16, at most 3840, with aspect ratio at most 3:1 and 655360-8294400 total pixels. Replaces the default 1K tier; cannot combine with a non-default resolution or aspect_ratio. Other base models return 400.

Base model identifier. Omit to use the default base model. Unknown ids are rejected with 400; base models that do not support this endpoint's capability are also rejected with 400.

output_format'png' | 'jpg'

Output image format (png, jpg). Default: png (will change to jpg on 2026-05-08).

Example request

{
  "images": [
    "iVBORw0KGgo...",
    "https://example.com/photo.jpg"
  ],
  "num_output_images": 2,
  "profile_ids": [
    "abc123",
    "def456"
  ],
  "prompt": "Turn [[def456]] into a vampire"
}

Response

Successful Response

imagesstring[]

Output image(s) as raw base64-encoded strings. Format matches the requested output_format. Populated when response_mode='bytes', empty otherwise.

download_urlsstring[]

Signed download URLs for each output image (24-hour expiry). Populated when response_mode='urls', empty otherwise.

Changes

No recorded changes to this operation across all 1 revision of this API.