Developers

No account yet? Create one for free, then make an API key under your avatar menu → API keys.

The Roilo API makes the same videos the website makes: you send product photos and a mode, Roilo writes the script, generates the scenes, adds captions and voice, and returns a finished video. Everything is JSON over HTTPS at https://roilo.co/api/v1. There is also a hosted MCP server for AI assistants (see MCP server below).

Credits are charged the same way as on the website: a hold when the video starts, the charge when it is delivered, and a refund if it fails. Each mode's cost is in GET /v1/modes.

The usual flow: (1) pick a mode from GET /v1/modes; (2) upload photos, or use public https links; (3) POST /v1/videos; (4) wait for the video.completed webhook, or poll GET /v1/videos/:id until status is completed or failed; (5) download output.video_url.

Conventions: request and response bodies are JSON (uploads are multipart); timestamps are ISO 8601 in UTC; video ids start with vid_ and file ids with file_; a video you do not own, or that does not exist, is 404 not_found.

Create a key under API keys in your account menu (a verified email is required; up to 10 live keys). The key starts with rk_live_ and is shown once. Send it as a bearer token on every request:

curl https://roilo.co/api/v1/me \
  -H "Authorization: Bearer rk_live_..."

A missing, malformed or revoked key gets 401 invalid_api_key. Each key can carry an optional monthly credit limit; when it is reached, creates get 402 key_credit_limit_reached. Keys only reach the API routes on this page, never the website's own routes.

POST /v1/videos returns 202 with the video object. Image references are either a file_… id from Upload a file, or a public https:// link (no IP addresses, no local host names; at most 2048 characters). Links are fetched before generation starts.

curl -X POST https://roilo.co/api/v1/videos \
  -H "Authorization: Bearer rk_live_..." \
  -H "Idempotency-Key: order-8731-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "balance",
    "product_images": ["file_2f1c...", "https://cdn.example.com/shoe-side.jpg"],
    "aspect_ratio": "9:16",
    "product": { "name": "Trail runner", "category": "fashion" },
    "webhook_url": "https://example.com/hooks/roilo",
    "metadata": { "order_id": "8731" }
  }'

Product categories: general, beauty, fashion, tech, food, fitness, home, pet, kids, health. Service categories: beauty_wellness, food_beverage, property, interior_renovation, fitness, clinic_health, education, automotive, events_media, general_service.

A create the account cannot pay for gets 402 insufficient_credits. By default at most 5 API videos per account can be in progress at once (429 too_many_active_videos).

{
  "id": "vid_9b2e...",
  "status": "processing",
  "progress": { "stage": "scene_creation", "percent": 40 },
  "output": null,
  "error": null,
  "brief": null,
  "review_expires_at": null,
  "mode": "balance",
  "credits_held": 10,
  "credits_charged": 0,
  "metadata": { "order_id": "8731" },
  "created_at": "2026-11-02T08:15:04.000Z",
  "completed_at": null
}

GET /v1/videos/:id reads one; GET /v1/videos?limit=20&cursor=… lists the videos on this account, newest first, as { "data": [...], "next_cursor": "..." | null } (limit is clamped to 1–100, default 20; pass next_cursor back as cursor for the next page, until it is null); DELETE /v1/videos/:id deletes one (204).

POST /v1/files returns 201 and takes one multipart part named file: JPEG, PNG or WebP, up to 50 MB, at most 20,000 px on an edge. The id is valid for 24 hours and can be used in more than one video in that time; up to 100 uploads per 24 hours.

curl -X POST https://roilo.co/api/v1/files \
  -H "Authorization: Bearer rk_live_..." \
  -F "[email protected]"
# -> { "id": "file_2f1c...", "expires_at": "2026-11-03T08:15:04.000Z" }

Send review: true and the video pauses at awaiting_review once Roilo has read the photos. Fetch it to see the brief Roilo drafted, then approve it, with or without edits. If you do nothing, it continues on its own at review_expires_at (24 hours by default).

curl -X POST https://roilo.co/api/v1/videos/vid_9b2e.../approve \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "brief": { "name": "Trail runner", "category": "fashion", "pain_point": "Wet trails, cold feet." } }'

The body is optional. brief takes the same fields as product on create; send only the ones you want to change, or no body to approve as is. It returns 200 with the video object, now processing. Approving a video that is not waiting gets 409 not_awaiting_review.

Set webhook_url on a video and Roilo POSTs JSON to it for video.awaiting_review, video.completed and video.failed. The body carries the full video object:

{
  "id": "evt_4a7d...",
  "type": "video.completed",
  "created_at": "2026-11-02T08:21:40.000Z",
  "data": { "id": "vid_9b2e...", "status": "completed", "output": { "video_url": "https://...", "...": "..." } }
}

Answer with any 2xx within 10 seconds. Redirects are not followed. On any other result Roilo makes six attempts in all, waiting about 1, 5, 15, 30 and 60 minutes between them. A URL that resolves to a private or local address is refused at once, with no retries. Events may arrive more than once; use the Roilo-Event-Id header (or id) to de-duplicate. The signed links inside a webhook body may have expired by the time a retry reaches you; fetch the video for fresh ones.

Every delivery is signed. The Roilo-Signature header is t=<unix seconds>,v1=<hex HMAC-SHA256> over `${t}.${rawBody}`, keyed by the key's webhook secret (whsec_…, shown once at creation; rotate it from the API keys page). Verify it like this, and reject anything older than 5 minutes:

import { createHmac, timingSafeEqual } from 'crypto';

// secret: the whsec_... shown once when the key was created (or rotated).
// rawBody: the request body bytes, exactly as received. header: the Roilo-Signature value.
export function verifyWebhook(secret, rawBody, header, now = Math.floor(Date.now() / 1000), toleranceSec = 300) {
  const parts = new Map();
  for (const piece of header.split(',')) {
    const i = piece.indexOf('=');
    if (i > 0) parts.set(piece.slice(0, i).trim(), piece.slice(i + 1).trim());
  }
  const t = Number(parts.get('t'));
  const given = parts.get('v1');
  if (!Number.isInteger(t) || !given) return false;
  if (Math.abs(now - t) > toleranceSec) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const a = Buffer.from(given, 'utf8');
  const b = Buffer.from(expected, 'utf8');
  return a.length === b.length && timingSafeEqual(a, b);
}

All four lists return { "data": [ ... ] } with the fields below; they are not paginated. GET /v1/actors and /v1/voices include your own and the stock ones.

Every error is one shape; param names the field when there is one:

{ "error": { "code": "photo_count_out_of_range", "message": "...", "param": "product_images" } }

Branch on the HTTP status and code; message is for people and its wording can change. Retry 429 and 5xx after a pause (reuse the same Idempotency-Key on create); fix the request on any other 4xx.

Limits are per key and per minute: 10 creates, 30 uploads, 120 of everything else (and 120 MCP calls). Each response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 rate_limited adds Retry-After.

Send an Idempotency-Key header (1–128 characters) on POST /v1/videos to make retries safe: for 24 hours the same key (per API key) returns the original response of a successful create, and the same key with a different body gets 422 idempotency_key_reused. While a create is still running, a second one on the same account gets 409 request_in_progress.

AI assistants that speak the Model Context Protocol can drive Roilo directly. The server is at https://roilo.co/api/mcp (Streamable HTTP, stateless) and authenticates with the same key as a bearer token. Add it to your assistant's MCP configuration:

{
  "mcpServers": {
    "roilo": {
      "type": "http",
      "url": "https://roilo.co/api/mcp",
      "headers": { "Authorization": "Bearer rk_live_..." }
    }
  }
}

Tools: create_video, get_video, list_videos, approve_video, delete_video, upload_image (base64, up to about 16 MB; give larger files or links to create_video as https links), list_modes, list_actors, list_voices, get_credits. Each tool takes the same fields and returns the same objects as the REST route behind it, and a failed call returns the same error body as a tool error. upload_image adds one code of its own, 422 invalid_base64. Credits are charged exactly as they are over REST.

Using the API or the MCP server means you accept the API and MCP access terms, including responsibility for how your own customers use what you build. Questions: [email protected].