Upload an image, get a handle
const url = 'https://api.stack.foldbun.com/v1/images';const form = new FormData();form.append('file', 'file');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.stack.foldbun.com/v1/images \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: multipart/form-data' \ --form file=@fileSend the file either as multipart/form-data (field file) or as the raw request body with
Content-Type: image/jpeg | image/png | image/webp. The image is sanitized (see the Overview); the handle is
content-addressed, so uploading the same picture again returns the same id (HTTP 200 instead of 201).
Free of charge. Not usable to probe other accounts’ images: handles only resolve inside the owning account.
Accepted formats and size limits are listed in the Overview.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”The image file, as a multipart form or as the raw request body.
object
The image file: JPEG, PNG or static WebP.
Raw JPEG bytes.
Raw PNG bytes.
Raw static WebP bytes.
Responses
Section titled “Responses”The same image was stored before; its existing handle is returned.
The stored image (sanitized, not resized). Coordinates in requests and responses are pixels of the oriented original.
object
Image handle: img_ plus the SHA-256 of the sanitized bytes.
Width of the oriented original in pixels (EXIF orientation applied).
Height of the oriented original in pixels (EXIF orientation applied).
Size of the stored image in bytes.
Media type of the stored image (the type of the upload).
Example
{ "id": "img_3b1f0c5e9a7d42c8b6e1f0a9d8c7b6a5f4e3d2c1b0a998877665544332211000", "width": 1008, "height": 672, "bytes": 184233, "contentType": "image/jpeg"}The image was sanitized and stored; the new handle is returned.
The stored image (sanitized, not resized). Coordinates in requests and responses are pixels of the oriented original.
object
Image handle: img_ plus the SHA-256 of the sanitized bytes.
Width of the oriented original in pixels (EXIF orientation applied).
Height of the oriented original in pixels (EXIF orientation applied).
Size of the stored image in bytes.
Media type of the stored image (the type of the upload).
Example
{ "contentType": "image/jpeg"}default
Section titled “default”The error envelope. The HTTP status follows the code; only retryable: true errors are worth repeating
unchanged. A failed call costs 0.
| Status | Codes |
|---|---|
| 400 | invalid_request, invalid_image (the image passed the upload checks but could not be decoded), unsupported |
| 401 | unauthorized |
| 402 | insufficient_balance |
| 403 | model_locked |
| 404 | not_found, image_not_found |
| 409 | idempotency_conflict, request_in_progress |
| 413 | payload_too_large |
| 429 | rate_limited, daily_limit_reached, too_many_batches (all with Retry-After) |
| 500 | internal_error |
| 502 | upstream_error, bad_model_output |
| 503 | model_unavailable, model_busy, unavailable (all with Retry-After) |
| 504 | upstream_timeout |
model_unavailable also covers a short loss of contact with the only GPU worker serving the model: for about a
minute after the loss, interactive calls answer it at once with a short Retry-After (5 s), while sync and
batch calls stay queued until their own deadline instead of failing.
Meaning and retry guidance for each code: Errors.
Body of every error response.
object
The error.
object
Stable machine-readable error code. Branch on this, not on message. Listed with the HTTP statuses under Responses.
Human-readable explanation. The wording can change.
True when repeating the same request unchanged can succeed.
Suggested wait before a retry in milliseconds; 0 when there is no hint.
Example
{ "error": { "code": "model_busy", "message": "model sam3 is busy; retry shortly", "retryable": true, "retryAfterMs": 5000 }}Headers
Section titled “Headers”Whole seconds to wait before retrying; present on 429 and 503.
Server-generated request id (16 hexadecimal characters); present on every response. Quote it when contacting support.