REST API

The same operations the MCP server exposes are available as plain HTTP for scripts and back-ends.

Base URL: https://www.filmera.ai/api/v1 · OpenAPI: /api/v1/openapi.json

Authentication

Authorization: Bearer fk_xxxxxxxx_…

Create keys under My page → API keys. A key is shown once; store it like a password. Each key has its own credit budget and can be revoked at any time.

Supabase OAuth access tokens (from the MCP sign-in flow) are accepted too.

Endpoints

| Method & path | What it does | | --- | --- | | GET /me | Who you are, plan, credit balance, this key's budget | | GET /projects · POST /projects | List / create projects | | GET /projects/{id} | Project context: canvas nodes, connections, scenes, timelines, best-take URLs | | GET /projects/{id}/media | Media pool with takes (?kind=gen|ref|audio) | | GET /models | Image, video and audio models | | GET /jobs/{id} | Job status; done includes result URLs | | GET /jobs?ids=a,b&wait=50 | Long-poll several jobs (max 50 s) | | POST /tools/{name} | Run any tool from the MCP catalog with a JSON body |

POST /tools/{name} covers everything else — creating nodes, importing media from a URL (import_media_from_url), generating, assembling the timeline, exporting. The body is the tool's input (see the OpenAPI document for schemas). Responses:

• 200 { "result": … } — JSON for data tools, a text summary for editing tools
• 422 { "error", "code": "tool_failed" } — the tool refused (bad input, node already generated, empty timeline, …). Fix the request and retry.

Errors

Every error is { "error": "<message>", "code": "<code>" }.

| Status | Code | Meaning | | --- | --- | --- | | 401 | unauthenticated · invalid_token | Missing or invalid Bearer | | 401 | key_reauth_required | The key's session expired — reconnect it under My page → API keys | | 401 | key_revoked | The key was revoked | | 402 | budget_exceeded | This agent's credit budget is used up | | 403 | forbidden · grant_revoked | Scope missing or access disconnected | | 429 | rate_limited | Slow down; see Retry-After | | 503 | retry | Token refresh in progress — retry after a moment |

Example

BASE=https://www.filmera.ai/api/v1
KEY=fk_…

# 1. a project
PROJECT=$(curl -s $BASE/projects -H "Authorization: Bearer $KEY" | jq -r '.projects[0].id')

# 2. an image node with your own prompt
NODE=$(curl -s $BASE/tools/create_image_node -H "Authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d "{\"project_id\":\"$PROJECT\",\"title\":\"Hero\",\"prompt\":\"portrait of a tired astronaut, 35mm\",\"asset_kind\":\"character\"}" \
  | jq -r '.result.node_id')

# 3. generate it (charged to your credits, within the key's budget)
curl -s $BASE/tools/generate_ref_nodes -H "Authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d "{\"project_id\":\"$PROJECT\",\"node_ids\":[\"$NODE\"]}"

# 4. see the result on the node
curl -s $BASE/projects/$PROJECT -H "Authorization: Bearer $KEY" | jq '.nodes[] | select(.id=="'$NODE'")'

Generation is asynchronous — poll GET /projects/{id} or GET /jobs?ids=… until the take is ready.

Last updated 2026-09-10. Prices, model specs and credit costs on this page are read from the live catalogue at build time.