Files

Start a file upload

Registers a file and returns a presigned upload_url. Uploading is three steps: (1) call this endpoint with the file name, MIME type, and size in bytes; (2) PUT the raw bytes to upload_url before upload_url_expires_at - send no Authorization header, the URL signature is the credential, and do send a Content-Type matching mime_type; (3) poll GET /api/v1/files/{id} until moderation_status is clean (usually a few seconds after the PUT), then pass id wherever an endpoint takes a file id (for example fabFileIds and referenceImageFabFileIds on POST /api/v1/image-edits). Unsupported types, a size over the upload limit, or a size that would exceed your storage quota are rejected with 400 before any URL is issued. Authenticate with an API key (b4m_live_) carrying files:write, or a JWT.

post/api/v1/files

Request

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

Request body

file_namestring required
mime_typestring required
file_sizeinteger required

Example request

{
  "file_name": "reference.png",
  "mime_type": "image/png",
  "file_size": 482133
}

Response

The file is registered; PUT its bytes to upload_url.

idstring required
upload_urlstring required
upload_url_expires_atstring required

Example response

{
  "id": "<fileId>",
  "upload_url": "https://<bucket>.s3.amazonaws.com/<key>?X-Amz-Signature=...",
  "upload_url_expires_at": "2026-09-29T12:10:00.000Z"
}

Changes

No recorded changes to this operation across all 3 revisions of this API.