Files & inputs
Pass reference images, first frames, videos, or audio via public HTTPS URLs, /v1/files uploads, or small data URIs.
Three ways to pass media inputs
Any file field in input (reference images, first/last frames, reference videos, audio) accepts:
- Public
https://URLs directly reachable by Kerox. - Kerox file URLs created via
POST /v1/files(up to 200 MB per file, retained for 7 days). - Inline base64 data URIs (
data:image/png;base64,...) up to 3 MB total per request (entire request body must stay ≤ 4 MB).
Presigned upload (recommended for large files)
Send file metadata as JSON to POST /v1/files. Kerox returns a presigned upload_url (valid for 15 minutes), the upload_headers to send with the upload, and the final url to pass into POST /v1/tasks. PUT the file to upload_url with those headers. The upload is signed for the content_type and size you declared, so size must be the file's exact size in bytes; a different size or type is refused.
# 1. Request a presigned PUT URL. "size" is the file's exact size in bytes.
RESPONSE=$(curl -s -X POST https://api.kerox.ai/v1/files \
-H "Authorization: Bearer $KEROX_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"filename\": \"frame.png\",
\"content_type\": \"image/png\",
\"size\": $(wc -c < frame.png | tr -d ' ')
}")
printf '%s\n' "$RESPONSE"
# 2. Take upload_url from the response and upload the bytes to it
UPLOAD_URL=$(printf '%s' "$RESPONSE" | sed -n 's/.*"upload_url": *"\([^"]*\)".*/\1/p')
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/png" \
--data-binary @frame.pngDirect multipart upload (≤ 4 MB)
For files up to 4 MB, upload in a single multipart/form-data request with form field file. The response returns status: "ready" and the usable url immediately.
curl -X POST https://api.kerox.ai/v1/files \
-H "Authorization: Bearer $KEROX_API_KEY" \
-F "file=@frame.png"Checking status & retention
- Call
GET /v1/files/{id}to check a presigned upload:"pending"until the bytes have arrived, then"ready". - Uploaded files are deleted automatically after 7 days.
- Uploads accept these content types:
image/jpeg,image/jpg,image/png,image/webp,image/bmp,image/tiff,image/gif,image/avif,image/heic,image/heif,video/mp4,video/quicktime,video/webm,audio/wav,audio/x-wav,audio/wave,audio/vnd.wave,audio/mpeg,audio/mp4. Any othercontent_typereturns HTTP422(invalid_parameter). Each model takes only some of them: check the model'sinput_schemafor its format and resolution limits.