Skip to main content

​
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.