> ## 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. # Edit > Edit images based on a text prompt. Provide input images (base64 or public URL) and a prompt describing the desired edit. Returns base64 images or signed download URLs. ## OpenAPI ````yaml https://api.photalabs.com/v1/phota/openapi.json post /v1/phota/edit 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/edit: post: tags: - Studio summary: Edit description: |- Edit images based on a text prompt. Provide input images (base64 or public URL) and a prompt describing the desired edit. Returns base64 images or signed download URLs. operationId: edit_v1_phota_edit_post requestBody: content: application/json: schema: $ref: '#/components/schemas/EditRequest' 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: EditRequest: 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: '' images: items: type: string type: array maxItems: 10 title: Images description: >- Input images as raw base64 strings or publicly accessible URLs. Both formats are auto-detected. Supported formats: JPEG, PNG, WebP, and HEIC/HEIF. Images larger than 4K (4096px) are automatically resized; for best results, provide images at 4K or below. profile_ids: items: type: string type: array title: Profile Ids description: >- Subset of your account's profiles relevant to this request. Your account holds all profiles, but only pass the ones belonging to the end-user whose photo is being edited. These profiles serve as candidates for identity preservation. The fewer profiles you pass, the easier it is for our system to determine which profiles are relevant. 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: EditRequest description: |- Request body for the edit endpoint. Input images can be provided as either raw base64-encoded bytes or publicly accessible URLs (e.g. ``https://example.com/photo.jpg``). Both formats are accepted and detected automatically. examples: - images: - iVBORw0KGgo... - https://example.com/photo.jpg num_output_images: 2 profile_ids: - abc123 - def456 prompt: Turn [[def456]] into a vampire 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 ````