Upload an input image
POST
/v1/uploads
const url = 'https://example.com/v1/uploads';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://example.com/v1/uploads \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: multipart/form-data' \ --form file=@fileStore an input image; returns {upload_key, image_url}.
Free (0 credits) — capability + rate-limit gated only. The upload_key
is what workflow dispatch accepts as product_image_s3_key /
source_image_s3_key.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters ”Request Body required
Section titled “Request Body required ” Media type multipart/form-data
Body_v1_upload_v1_uploads_post
object
file
required
File
The input image (jpeg/png/webp, ≤25 MB).
string format: binary
Responses
Section titled “ Responses ”Successful Response
Media type application/json
UploadResponse
POST /v1/uploads response — the durable handle + a preview URL.
upload_key is what workflow requests accept as product_image_s3_key /
source_image_s3_key (the studio s3_key IS the upload handle on this
surface — PRD §6). image_url is a presigned preview URL and is NOT
accepted back as an input.
object
upload_key
required
Upload Key
Durable upload handle — pass into workflow dispatch.
string
image_url
required
Image Url
Short-lived presigned preview URL (not an input handle).
string
Example generated
{ "upload_key": "example", "image_url": "example"}Validation Error
Media type application/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationErrorobject
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Example generated
{ "detail": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ]}