Create an upload target

POST /uploads

Prepare storage for a customer photo. The response contains a signed PUT target and the photo URL to use after that upload succeeds.

Request

Authentication: X-Antla-SDK-Key: YOUR_ANTLA_SDK_KEY. Content-Type: application/json.

Uses the shared IP rate limit. See Errors and rate limits.

Body field	Type	Required	Description
contentType	string	Yes	One of image/jpeg, image/png, image/webp, image/heic, image/heif, image/avif.
customKey	string	No	Trimmed prefix, 1-100 letters, digits, underscores or hyphens.

Example request

curl --fail-with-body -X POST \
  "https://app-antla.com/api/headless/uploads" \
  -H "X-Antla-SDK-Key: YOUR_ANTLA_SDK_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "contentType": "image/jpeg"
}'

Successful response

HTTP 200, JSON envelope:

{
  "data": {
    "uploadUrl": "https://storage.example.com/presigned-upload-url",
    "imageUrl": "https://cdn.example.com/customer-photo.jpg"
  }
}

PUT the image bytes to uploadUrl using the selected MIME type:

curl --fail-with-body -X PUT "RETURNED_UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @customer-photo.jpg

Do not send the SDK key to the upload target. Check that the PUT succeeded before starting a generation. The signed URL expires after 600 seconds. An upload target is not a generation job.

The browser SDK rejects files over 10 MiB before upload. This endpoint does not apply that limit. See Images and uploads.

Errors

400 Invalid upload request or Invalid JSON body. 500 Could not create upload URL. The storage PUT uses its own status codes, not the Antla JSON envelope. See Errors and rate limits.