Upload one image

Stores the request body as an asset in one call: the bytes are the body, the parameters are the query string. Send the image as the raw body with its own Content-Type (image/jpeg, image/png, …) and a Content-Length, or as multipart/form-data with a file part. The asset is created in PROCESSING and reaches DONE once ingest has written dimensions and metadata — poll POST /api/v1/assets/status or subscribe to the webhook.

The type is the declared Content-Type when it is an image type this product takes, else the extension of name (or the multipart file name); neither → 400 unsupported_format. Bytes the account already holds as a DONE asset (same SHA-1) come back as that asset with existing: true and nothing new is stored.

LIMITS: one file per call, at most 25 MB (413 payload_too_large); a raw body needs Content-Length (400 invalid_param). Over this node's concurrent-upload capacity → 503 provider_unavailable with Retry-After, retryable. No Idempotency-Key (contract §3): the same bytes are the same asset, so re-sending is already safe.

USE THIS WHEN:

• You hold one image of up to 25 MB and want an asset_id for a job

DO NOT USE WHEN:

• The file is over 25 MB, or you have many → POST /api/v1/assets/stage-upload, PUT, then finish-upload (the bytes then go straight to the object store)
• The image is at a public URL → POST /api/v1/assets/from-url
• You only want one image transformed and back → POST /api/v1/images/transform