Images

Edit an image

Queues an edit of an existing image and returns the quest that will carry the result, before the render runs. Poll GET /api/v1/quests/{id} until status is "done" (see the editImage200PollResult schema). image is the URL of the source image; fabFileIds must name at least one file, and the first is the inpainting mask. referenceImageFabFileIds adds up to 15 style anchors after the source image, so the mask always applies to the source; only gpt-image models accept them, and sending any with another model is rejected with a 400 rather than ignored. Both id fields take ids from POST /api/v1/files: upload each file, poll GET /api/v1/files/{id} until moderation_status is clean, then pass its id. An id that is not yet clean fails the edit on the polled quest. image takes a URL rather than an id, so a source uploaded the same way is passed as its download_url, which must still be unexpired when the render runs. The edited image is not a file id: read it from files[].url on the polled quest, not from GET /api/v1/files/{id}. seed makes an edit reproducible on BFL (FLUX) models only; gpt-image and Gemini models ignore it. Credits are checked when the render runs, so insufficient credits arrive on the polled quest rather than as a 422. POST /api/ai/edit-image is a legacy alias of this endpoint. Authenticate with an API key (b4m_live_) or a JWT.

Optional callbackUrl: an https URL that receives a signed POST when the quest settles (success, failure, or a stop; a failed render is type: "error" in the body, same as the poll). The body is the GET /api/v1/quests/{id} response. Headers: X-Webhook-Event-ID (the same on every attempt for one settlement; delivery is at-least-once, so dedupe on it, and a retried quest settles again under a new one), X-Webhook-Delivery-ID (unique per attempt), X-Webhook-Timestamp (unix seconds), X-Webhook-Signature-256 (sha256= + hex HMAC-SHA256 of <timestamp>.<raw body> keyed with the API key's callback signing secret), and X-Event-Type: quest.settled. Delivery makes up to 5 attempts, retrying on a 5xx, 408, 429, timeout or network error - never on any other 4xx, and redirects are not followed; your endpoint must answer 2xx within 10 seconds. Requires API-key authentication and a signing secret on that key (returned once at key creation, or via POST /api/user-api-keys/{id}/callback-secret). A callbackUrl is rejected with a 400 when the request is not API-key authenticated, the key has no signing secret, the URL resolves to a private address, or the deployment does not deliver callbacks; a URL that is not https fails request validation with a 422. Polling still works whether or not callbackUrl is set.

post/api/v1/image-edits

Request

  • Base URL: https://your-deployment.example.com
  • URL: https://your-deployment.example.com/api/v1/image-edits
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

promptstring required
nnumber
quality'standard' | 'hd' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto'
response_format'b64_json' | 'url'
style'vivid' | 'natural'
background'transparent' | 'opaque' | 'auto' | 'null' nullable
widthnumber
heightnumber
aspect_ratiostring
sessionIdstring required
questIdstring
organizationIdstring nullable

The organization to bill: one you belong to, or null for your personal credits. Omitted bills your home organization, or your personal credits if you have none. An organization-billed API key always bills its own organization: omit this or set it to the key's organization; any other value, null included, is rejected with a 403 (errorCode: billing_organization_mismatch).

fabFileIdsstring[]
referenceImageFabFileIdsstring[]
imagestring required
output_format'png' | 'jpeg' | 'webp' | 'null' nullable
seednumber nullable
callbackUrlstring uri

Optional https URL that receives one signed POST when the job settles (success or failure). Requires API-key authentication and a callback signing secret on that key. The body is the GET /api/v1/quests/{id} response. Verify it with the X-Webhook-Signature-256 header: sha256= + hex HMAC-SHA256 of <X-Webhook-Timestamp>.<raw body> keyed with the signing secret. Polling keeps working either way.

Example request

{
  "prompt": "replace the sky with a starry night",
  "model": "gpt-image-1",
  "sessionId": "664f1c2b9a1e4d0012ab34aa",
  "image": "https://example.com/source.png",
  "fabFileIds": [
    "664f1c2b9a1e4d0012ab34bb"
  ]
}

Response

Edit queued - NOT a finished render. The body is the quest itself, with no images yet; its outcome arrives on GET /api/v1/quests/{id}.

idstring required
status'pending' | 'stopped' | 'running' | 'done'
type'message' | 'oob' | 'error' | 'system' | 'voice_transcript'
errorCode'insufficient_credits' | 'spend_cap_exceeded'
replystring nullable
repliesstring[]
sessionIdstring required
imagesstring[]

Changes

No recorded changes to this operation across all 1 revision of this API.