PHphotalabs
Studio

Generate

Generate images from a text prompt without input images.

Provide a prompt describing the desired image. Returns base64 images or signed download URLs.

post/v2/phota/generate

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.

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'auto' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' nullable

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'flux-2' | 'flux-2-pro' | 'gpt-image-2' | 'gpt-image-2.5-flare' | 'gpt-image-2.5-sunburst' | 'nb2' | 'nb2.1' | 'qwen-image-2' | 'seedream-5-pro'

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

{
  "num_output_images": 1,
  "prompt": "Generate a photo of [[abc123]] on a tropical beach"
}

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.