Binary inputs

Private direct uploads

Image, audio, and video inputs never travel through an arbitrary remote URL. Your server declares the file, uploads it directly to a short-lived private location, completes verification, and then sends the verified upload_id to an eligible engine.

Step 1: calculate exact metadata

Calculate the byte length and lowercase SHA-256 hash from the exact bytes that will be uploaded. Do not hash a resized preview and upload a different file.

# Linux/macOS
BYTES=$(wc -c < input.png | tr -d ' ')
SHA256=$(sha256sum input.png | cut -d ' ' -f1)

# PowerShell
$bytes = (Get-Item -LiteralPath input.png).Length
$sha256 = (Get-FileHash -Algorithm SHA256 -LiteralPath input.png).Hash.ToLower()

Step 2: create an upload

curl "$URTHEPRODUCT_BASE_URL/v1/uploads"   -X POST   -H "Authorization: Bearer $URTHEPRODUCT_API_KEY"   -H "Idempotency-Key: upload-create-001"   -H "Content-Type: application/json"   -d '{"purpose":"image_input","filename":"input.png","mime_type":"image/png","size_bytes":123456,"sha256":"64-lowercase-hex-characters"}'

Step 3: PUT bytes to the returned URL

# Read upload_url and required_headers from the create response.
curl "$UPLOAD_URL"   -X PUT   -H "Content-Type: image/png"   -H "x-upsert: false"   --data-binary @input.png

Use the exact upload_url, HTTP method, and headers returned by the API. Do not log the signed URL or reuse it after its 30-minute expiry. A signed upload is private and cannot overwrite an existing object.

Step 4: complete verification

curl "$URTHEPRODUCT_BASE_URL/v1/uploads/$UPLOAD_ID/complete"   -X POST   -H "Authorization: Bearer $URTHEPRODUCT_API_KEY"   -H "Idempotency-Key: upload-complete-001"   -H "Content-Type: application/json"   -d '{"sha256":"the-same-64-character-sha256"}'

Completion checks ownership, expiry, declared size, calculated checksum, MIME, and file magic bytes. A mismatch rejects and removes the object. Only status: verified may be used for generation.

Step 5: use the verified identifier

{
  "prompt": "Place the supplied authorized product on a neutral studio background.",
  "input_upload_id": "upl_example_identifier",
  "output_format": "png"
}

Common upload failures