Uploading

Upload a reference image

A picture for a generation to follow. Pass the referenceId it answers as any generation endpoint's referenceId. PNG only, up to 2MB; 512px or smaller is plenty.

POST/packs/{pack}/references

Path parameters

packstringrequired

The pack's slug, as returned by the packs endpoints.

Body

fileobjectrequired

The PNG. Exactly one of upload, url, base64 or text.

uploadstring

The upload id from POST /uploads, after PUTting the file to its URL. The way to send anything big, or anything already on disk.

urlstring

A public https URL to fetch the file from.

base64string

The file's bytes as base64 (a data: URI is fine). Up to 8MB.

textstring

The file as text, for formats that are text (model JSON, .bbmodel). Up to 8MB.

Response · 201

Stored.

packstringrequired

The pack it belongs to.

referenceIdstringrequired

Pass as referenceId when generating.

Error codes

Branch on error.code, never on the message.

file_fetch_failed400

A file given by url couldn't be downloaded.

invalid_request400

Something in the body or query is wrong. message says what.

invalid_api_key401

The key isn't one of ours, or it has been revoked.

missing_api_key401

No Authorization: Bearer header was sent.

wrong_key_kind401

An MCP key sent to the REST API, or an API key sent to the MCP server. Each only opens its own.

forbidden403

Valid key, but not permitted to do this in this pack.

plan_required403

The key is valid, but its account is on Starter. The API needs a paid plan.

not_found404

No such pack, asset or job.

upload_not_found404

No upload by that id. Uploads expire after fifteen minutes and are used once.

file_too_large413

The file is over the limit for what it's being used as. message says the limit.