---
title: "Generate"
method: POST
path: "/v2/phota/generate"
tags: ["Studio"]
---

# Generate

`POST /v2/phota/generate`

## Request

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

Generate images from a text prompt without input images.

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

## Request body

- GenerateRequest: Request body for the generate endpoint. Provide a text prompt describing the image you want to create. Reference profiles inline using ``[[profile_id]]`` syntax to specify which people should appear in the generated image.
  - `async` boolean: 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_url` string, nullable: Optional https URL we POST the signed result to on completion. Best-effort (polling remains authoritative). Requires async=true.
  - `client_request_id` string, 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.
  - `prompt` string: Text prompt describing the desired edit.
  - `num_output_images` integer: 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_resolution` string, 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).

## Response `200`

Successful Response

- EditResponse: Response returned by the edit, generate, and enhance endpoints.
  - `images` string[]: Output image(s) as raw base64-encoded strings. Format matches the requested output_format. Populated when response_mode='bytes', empty otherwise.
  - `download_urls` string[]: Signed download URLs for each output image (24-hour expiry). Populated when response_mode='urls', empty otherwise.
  - `known_subjects` KnownGeneratedSubjectCounts, required: Counts of known subjects generated, keyed by profile ID.
    - `counts` object: Mapping of profile ID to the number of times that subject was generated.

## Other responses

- `202`: Async job accepted; poll job_id at poll_url.
- `400`: Invalid request, content moderation violation, or profiles of mixed model versions.
- `401`: Invalid API key in the X-API-Key header.
- `402`: Insufficient prepaid credit balance.
- `403`: Missing X-API-Key header (no API key provided).
- `404`: Resource not found.
- `422`: No image was produced (not charged, retryable), or request validation failed.
- `500`: Internal error.
- `503`: Service temporarily unavailable.
- `504`: Synchronous request exceeded the 600s limit; resubmit with `async: true`.

---

[API](https://skmtc.dev/photalabs/apis/phota-api.md) - [All operations](https://skmtc.dev/photalabs/apis/phota-api/llms.txt) - [OpenAPI document](https://skmtc.dev/photalabs/apis/phota-api/revisions/951f156f1f6c?raw)