> ## Documentation Index > Fetch the complete documentation index at: https://docs.photalabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Generate > Generate images from a text prompt without input images. Provide a prompt describing the desired image. Returns base64 images or signed download URLs. ## OpenAPI ````yaml https://api.photalabs.com/v1/phota/openapi.json post /v1/phota/generate openapi: 3.1.0 info: title: Phota API description: Create and manage profiles for photo editing and enhancement. version: v0.7.0 servers: - url: https://api.photalabs.com security: [] tags: - name: Studio description: Image editing, generation, and enhancement. - name: Profiles description: 'Profile lifecycle: create, query, delete.' paths: /v1/phota/generate: post: tags: - Studio summary: Generate description: |- Generate images from a text prompt without input images. Provide a prompt describing the desired image. Returns base64 images or signed download URLs. operationId: generate_v1_phota_generate_post requestBody: content: application/json: schema: $ref: '#/components/schemas/GenerateRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/EditResponse' '202': description: Async job accepted; poll job_id at poll_url. content: application/json: schema: $ref: '#/components/schemas/JobHandle' '400': description: >- Invalid request, content moderation violation, or profiles of mixed model versions. content: application/json: schema: $ref: '#/components/schemas/PhotaError400Response' '401': description: Invalid API key in the X-API-Key header. '402': description: Insufficient prepaid credit balance. '403': description: Missing X-API-Key header (no API key provided). '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/PhotaError404Response' '422': description: >- No image was produced (not charged, retryable), or request validation failed. content: application/json: schema: $ref: '#/components/schemas/PhotaError422Response' '500': description: Internal error. content: application/json: schema: $ref: '#/components/schemas/PhotaError500Response' '503': description: Service temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/PhotaError503Response' '504': description: >- Synchronous request exceeded the 600s limit; resubmit with `async: true`. content: application/json: schema: $ref: '#/components/schemas/PhotaError504Response' security: - APIKeyHeader: [] components: schemas: GenerateRequest: properties: async: type: boolean title: Async description: >- 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. default: false callback_url: anyOf: - type: string - type: 'null' title: Callback Url description: >- Optional https URL we POST the signed result to on completion. Best-effort (polling remains authoritative). Requires async=true. client_request_id: anyOf: - type: string - type: 'null' title: Client Request Id description: >- Idempotency key. A retried submit with the same value returns the original job instead of creating (and charging for) a new one. response_mode: type: string enum: - bytes - urls title: Response Mode description: >- Response delivery mode. 'bytes': return base64-encoded image data (default). 'urls': return signed download URLs (24-hour expiry) instead of image bytes. default: bytes prompt: type: string title: Prompt description: Text prompt describing the desired edit. default: '' num_output_images: type: integer maximum: 4 minimum: 1 title: Num Output Images description: Number of output images to generate (1-4). default: 1 aspect_ratio: anyOf: - type: string enum: - auto - '1:1' - '3:4' - '4:3' - '9:16' - '16:9' - type: 'null' title: Aspect Ratio description: >- 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: type: string enum: - 1K - 2K - 4K title: Resolution description: >- Output resolution (1K, 2K, 4K). Per-model support varies; see /models. default: 1K quality: anyOf: - type: string enum: - auto - low - medium - high - type: 'null' title: Quality description: >- Quality tier (auto, low, medium, high). Only supported by gpt-image-2; passing this field for other models returns 400. Omit (or pass 'auto') to let the provider pick — for gpt-image-2 this resolves to OpenAI's auto tier. Lower tiers reduce output tokens and therefore settled cost. base_model: type: string enum: - flux-2 - flux-2-pro - gpt-image-2 - nb2 - qwen-image-2 - seedream-5-pro title: Base Model description: >- 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. default: nb2 output_format: type: string enum: - png - jpg title: Output Format description: >- Output image format (png, jpg). Default: png (will change to jpg on 2026-05-08). default: png type: object title: GenerateRequest description: |- 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. examples: - num_output_images: 1 prompt: Generate a photo of [[abc123]] on a tropical beach EditResponse: properties: images: items: type: string type: array title: Images description: >- Output image(s) as raw base64-encoded strings. Format matches the requested output_format. Populated when response_mode='bytes', empty otherwise. download_urls: items: type: string type: array title: Download Urls description: >- Signed download URLs for each output image (24-hour expiry). Populated when response_mode='urls', empty otherwise. known_subjects: $ref: '#/components/schemas/KnownGeneratedSubjectCounts' description: >- Dictionary mapping a known subject's `profile_id` to the number of times they were generated. If multiple variations are generated, this will be the aggregated count across all variations. type: object required: - known_subjects title: EditResponse description: Response returned by the edit, generate, and enhance endpoints. JobHandle: properties: job_id: type: string title: Job Id description: Opaque job identifier. Poll GET /v1/jobs/{job_id} for status. status: type: string const: pending title: Status description: >- Always 'pending' at submit; transitions to running then succeeded/failed. default: pending poll_url: type: string title: Poll Url description: Relative path to poll for job status, e.g. '/v1/jobs/'. type: object required: - job_id - poll_url title: JobHandle description: >- 202 response when an edit/generate/enhance/remix is submitted with async=true. PhotaError400Response: properties: detail: type: string title: Detail description: Human-readable error message. code: type: string enum: - CONTENT_MODERATION - INVALID_REQUEST - MIXED_PROFILE_MODEL_VERSIONS title: Code description: Machine-readable error code. request_id: type: string title: Request Id description: Unique request identifier for support. type: object required: - detail - code - request_id title: PhotaError400Response description: Error response for 400 Bad Request. PhotaError404Response: properties: detail: type: string title: Detail description: Human-readable error message. code: type: string enum: - NOT_FOUND - PROFILE_NOT_FOUND - PROFILE_NOT_READY title: Code description: Machine-readable error code. request_id: type: string title: Request Id description: Unique request identifier for support. type: object required: - detail - code - request_id title: PhotaError404Response description: Error response for 404 Not Found. PhotaError422Response: properties: detail: type: string title: Detail description: Human-readable error message. code: type: string enum: - NO_IMAGE_GENERATED - INVALID_REQUEST title: Code description: Machine-readable error code. request_id: type: string title: Request Id description: Unique request identifier for support. type: object required: - detail - code - request_id title: PhotaError422Response description: >- Error response for 422 Unprocessable Content. Covers the model completing without producing an image (``NO_IMAGE_GENERATED``, not charged, retryable) and request-body validation failures (``INVALID_REQUEST``). PhotaError500Response: properties: detail: type: string title: Detail description: Human-readable error message. code: type: string const: INTERNAL_ERROR title: Code description: Machine-readable error code. request_id: type: string title: Request Id description: Unique request identifier for support. type: object required: - detail - code - request_id title: PhotaError500Response description: Error response for 500 Internal Server Error. PhotaError503Response: properties: detail: type: string title: Detail description: Human-readable error message. code: type: string enum: - SERVICE_UNAVAILABLE - INPUT_IMAGE_FETCH_FAILED title: Code description: Machine-readable error code. request_id: type: string title: Request Id description: Unique request identifier for support. type: object required: - detail - code - request_id title: PhotaError503Response description: Error response for 503 Service Unavailable. PhotaError504Response: properties: detail: type: string title: Detail description: Human-readable error message. code: type: string const: TIMEOUT title: Code description: Machine-readable error code. request_id: type: string title: Request Id description: Unique request identifier for support. type: object required: - detail - code - request_id title: PhotaError504Response description: >- Error response for 504 Gateway Timeout (synchronous time budget exceeded). KnownGeneratedSubjectCounts: properties: counts: additionalProperties: type: integer type: object title: Counts description: >- Mapping of profile ID to the number of times that subject was generated. type: object title: KnownGeneratedSubjectCounts description: Counts of known subjects generated, keyed by profile ID. securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````