Skip to Content

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:

  1. Public https:// URLs directly reachable by Kerox.
  2. Kerox file URLs created via POST /v1/files (up to 200 MB per file, retained for 7 days).
  3. 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.png

Direct 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 other content_type returns HTTP 422 (invalid_parameter). Each model takes only some of them: check the model's input_schema for its format and resolution limits.