Uploads

Send your own file (a product shot, a face, a clip, a recording) and get an ast_ id to put in a config. Three steps. Two are RiffAds calls.

The three steps

curl -s -X POST https://app.riffads.com/api/v1/uploads \
  -H "Authorization: Bearer $RIFFADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "product-hero.png",
    "content_type": "image/png",
    "size_bytes": 318244
  }'

{
  "ok": true,
  "asset_id": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0011",
  "upload_url": "https://<storage-host>/riffads/orgs/<org-id>/assets/ast_0193c8f0a1b24e7f9d3c5a6b7e8f0011.png?X-Amz-Signature=...",
  "upload_expires_at": "2026-09-17T10:09:11.000Z",
  "upload_expires_in_seconds": 300,
  "kind": "image",
  "content_type": "image/png",
  "size_bytes": 318244,
  "max_bytes_for_kind": 20971520,
  "content_checked": true,
  "next_action": "Send the file with a single HTTP PUT request at upload_url, with the same content type and exactly 318244 bytes, within 5 minutes. Then call finalize_upload with this asset_id. The file cannot be used in a generation until that second call comes back usable. Images are checked against our content policy at that point."
}

curl -s -X PUT "https://<storage-host>/riffads/orgs/<org-id>/assets/ast_0193c8f0a1b24e7f9d3c5a6b7e8f0011.png?X-Amz-Signature=..." \
  -H "Content-Type: image/png" \
  --data-binary @product-hero.png

curl -s -X POST \
  https://app.riffads.com/api/v1/uploads/ast_0193c8f0a1b24e7f9d3c5a6b7e8f0011/finalize \
  -H "Authorization: Bearer $RIFFADS_API_KEY"

{
  "ok": true,
  "asset_id": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0011",
  "scan_status": "clean",
  "usable": true,
  "kind": "image",
  "duration_ms": null,
  "next_action": "This file is ready. Pass this asset_id into a capability config wherever it asks for a file, then call estimate_generation before you spend anything."
}

• CLI: riffads upload <file> does all three and prints the asset id. Commands.
• MCP: create_upload and finalize_upload, both in the spend set. Tools.

Reserve

• Scope Generate.
• Answers 201, no Location header.
• Strict body: an unknown key is 400 invalid_config.

Accepted types and sizes

Kind comes from content_type. Any other type is refused, and the message lists every accepted type.

Response fields

The PUT

Break a rule here and it fails at finalize, not at the PUT.

• One request. Single PUT. No multipart, no chunks.
• Same content type you declared.
• Exactly size_bytes bytes.
• Within 5 minutes, once. A used or expired link is gone.

A reservation counts toward the pending cap until you finalize it or it ages out.

Finalize

• Scope Generate.
• Answers 200. No body.
• Safe to call twice. A scanned file answers from its stored status. No second check.

A refused file is a 200

{
  "ok": true,
  "asset_id": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0011",
  "scan_status": "flagged",
  "usable": false,
  "kind": "image",
  "duration_ms": null,
  "next_action": "This file was refused by our content policy and can never be used in a generation. Do not call finalize_upload again and do not send the same file again: the answer will not change. Use a different file."
}

What finalize checks

• The real file signature must match the declared kind. Renaming the file doesn't help.
• Images are decoded: max 16,384 px per side, max 40,000,000 px total. The decoded type must match the signature.
• Fail any check: the file is deleted and the reservation is spent. Reserve again.

Finalize errors

Using the asset id

Put the id where the capability config asks for a file. The field name and shape come from GET /capabilities/{capability_id}. Never guess. Capabilities API.

Tools take a plain array of ids:

{
  "source_video": ["ast_0193c8f0a1b24e7f9d3c5a6b7e8f0011"],
  "caption_style": "punch"
}

Image and video models take objects, so a prompt can point at an alias:

{
  "prompt": "The bottle on a kitchen counter at golden hour, in the style of /image1",
  "reference_images": [
    {
      "assetId": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0011",
      "alias": "image1",
      "role": "reference"
    }
  ]
}

• Asset ids must match ^ast_[0-9a-f]{32}$. A made-up string like "product-hero.png" fails later, with a less clear error.
• A talking actor face goes on the submit body as actor_image_asset_id, not in config. Generations API.
• Finalize before you estimate. Estimates for length-based capabilities read the measured duration_ms.

Submit names a file that isn't ready

Default answer: 409 input_not_ready, retryable. Wait a moment, don't resend at once. RiffAds checks the named files again first, and may answer with something final instead:

The blocked message reads: "One of the files in this request was refused by our content policy (ast_...), so it can never be used in a generation. Sending this request again will be refused again. Upload a different file."

Limits

• Each key has its own rate bucket.
• The pending cap is workspace wide. Finish your reservations or wait 15 minutes.

Not here

• No list, no delete. Lost an id? Upload again.
• No multipart. Bytes go to storage, never through /api/v1.
• No browser calls. It needs a secret key and sends no CORS headers. Call it from a server.

More: limits, error codes, content policy.