Edit an existing image using a text prompt, with an optional mask that constrains where the edit is applied. OpenAI-compatible wire shape — the openai SDKs work with a base_url swap to https://api.tokenfactory.omniva.com/v1.
Image editing is in Beta. Parameters and response shape may shift before GA.
#Authentication
Bearer token in the Authorization header. See Authentication for how to mint and rotate keys.
#Request
Body is multipart/form-data (not JSON). File fields carry binary image bytes; text fields carry the prompt and options.
| Field | Type | Description |
|---|---|---|
imagerequired | file | The source image to edit. PNG, JPEG, or WebP. Square images get the broadest model support. |
promptrequired | string | Description of the edit. Be specific about what should change and what should remain. |
mask | file | Optional PNG with transparent regions marking where the edit should apply. Same dimensions as image. Without a mask, the model decides which regions to alter. |
modelrequired | string | ID of the image model to use. Browse the Image tab in Model Library. |
n | integer | Number of edited images to return. Default: 1 |
size | string | Pixel dimensions of the output, e.g. "1024x1024". Must match a size the model supports. Default: 1024x1024 |
response_format | string | Either "url" (hosted URL with a short TTL) or "b64_json" (base64-encoded bytes inline). Default: url |
The image surface is evolving — model-specific parameters may appear here before they're documented. Open Playground to see the canonical parameter set for any image model in your workspace.
#Response
Same shape as Image generations. Each entry has url or b64_json depending on response_format.
#Errors
| Status | Code | When |
|---|---|---|
| 400 | invalid_payload | image, prompt, or model missing; or mask dimensions do not match image. |
| 401 | unauthorized | Missing or invalid Bearer token. |
| 404 | model_not_found | Unknown image model. |
| 413 | payload_too_large | Combined upload exceeded the per-request size limit. |
| 429 | rate_limited | Rate limit or quota exceeded. |
| 503 | upstream_unavailable | No healthy upstream — retry with backoff. |
See Errors for the full error envelope and retry guidance.