Skip to main content

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.

​
v0.4.0 — Quality selection on GPT Image 2

​
New features

  • quality parameter on /edit and /generate. Optional, accepts "auto", "low", "medium", or "high". Only supported when base_model is gpt-image-2; sending quality for any other model returns HTTP 400. Settlement remains token-driven, so partners pay for the actual output tokens regardless of tier.

​
Behavior changes

  • Default quality on gpt-image-2 is now "auto" — Requests that omit quality previously landed on the "high" tier; they now land on OpenAI’s auto tier. Pass "quality": "high" explicitly if you want the previous behavior.

​
v0.3.0 — Base model selection

​
New features

  • base_model parameter on /edit and /generate. Pick between nb2 (Nano Banana 2, default), gpt-image-2 (GPT Image 2), qwen-image-2, flux-2, and reve. Phota’s identity layer composes on top of any of them. Unknown ids return HTTP 422; unsupported resolutions (e.g. 4K on flux-2 or qwen-image-2) return HTTP 400. See Base model selection.
  • Per-model pricing — Each base model has its own per-image rate plus a with-identity rate that applies when a trained profile is recognized in the output. GPT Image 2 is billed per token. See Pricing.

​
Improvements

  • Less wardrobe and background leakage on /generate — Clothing, accessories, and background from the profile’s training photos are less likely to bleed into /generate outputs. Prompts that specify wardrobe or setting are followed more reliably.

​
v0.2.1

​
New features

  • Enhance prompts — The /enhance endpoint now accepts an optional prompt field with text instructions to guide the enhancement. When omitted, enhancement parameters continue to be inferred automatically.

​
v0.2.0

​
New features

  • Output format selection — New output_format parameter on edit, generate, and enhance endpoints. Choose between "png" (lossless) and "jpg" (smaller files). Default: "png".
  • Response mode — New response_mode parameter ("bytes" or "urls") on edit, generate, and enhance endpoints. Default: "bytes" (base64-encoded images). Set to "urls" to receive signed CDN download URLs (24-hour expiry) instead. Each mode populates its respective response field; the other is returned empty.

​
Deprecation notices

  • Default format change — The default output_format will change from "png" to "jpg" on 2026-05-08. Set output_format explicitly in your requests to avoid disruption. Responses include X-Phota-Deprecation-Date: 2026-05-08 header.

​
v0.1.1

​
New features

  • Profile tags — Profiles now accept an optional tag field on creation, allowing you to namespace profiles by your own identifiers (e.g., end-user IDs). GET /profiles/ids accepts a ?tag= query parameter to filter profiles by tag.

​
Improvements

  • Image format handling — Input images exceeding 4096px are automatically resized to 4K. Supported formats (JPEG, PNG, WebP, HEIC/HEIF) are now documented in the OpenAPI spec field descriptions. PNGs are automatically transcoded to optimized JPG.
  • Request tracing — Every response now includes an X-Request-Id header, and error responses include a request_id field. Use these when reporting issues for faster debugging.
  • Request timeout — Maximum request duration increased from 360s to 600s, fixing 504 timeouts on long-running generation requests.
  • Content moderation errors — Content moderation blocks now return HTTP 400 with error type CONTENT_MODERATION instead of HTTP 500.

​
Bug fixes

  • Training error messages — When no subject is detected in training images, the API now returns a descriptive HTTP 400 error instead of a generic 500 error.

​
v0.1.0 — Initial release

This is the first public release of the Phota API.

​
Endpoints

Studio
  • POST /edit — Edit images using a text prompt and optional profile references. Supports base64 and URL input images.
  • POST /generate — Generate new images from a text prompt alone, without any input image. Supports profile references for identity preservation.
  • POST /enhance — Automatically enhance a photo without a text prompt.
Profiles
  • POST /profiles/add — Create a new profile from – reference image URLs. Training runs asynchronously.
  • GET /profiles/{profile_id}/status — Poll the training status of a profile (IN_PROGRESS, READY, or ERROR).
  • GET /profiles/ids — List all profile IDs for the authenticated account.
  • GET /profiles/{profile_id}/profile_picture — Retrieve a profile picture as a JPEG image.
  • DELETE /profiles/{profile_id} — Permanently delete a profile and all associated data.

​
Features

  • Identity preservation — Train profiles from reference photos and use them across edits and generations. Reference profiles in prompts with the [[profile_id]] syntax to control where specific people appear.
  • Pro mode — Available on edit and generate endpoints. Enables better instruction following and quality at the cost of higher costs. Unlocks aspect ratio and resolution control.
  • Multi-image output — Generate up to 4 output images per request.
  • Flexible input — Accept images as raw base64 strings or publicly accessible URLs.
  • Aspect ratio and resolution control — Choose from 11 aspect ratios and up to 4K resolution when pro mode is enabled.
  • Billing metadata — Responses include known_subjects with counts of known subjects generated per profile, used for billing purposes.

​
Authentication

  • All endpoints require the X-API-Key header. See Authentication for details.