The Storias API

Quick start

Five calls to a finished film

Set STORIAS_API_KEY once and run these in order.

1. 1 · Who am I, and what can I spend?

   Every call is a bearer key, so start by reading it back — a good way to prove the key works before anything spends credits.

   Copycurl https://api.storiasai.com/v1/me \
     -H "Authorization: Bearer $STORIAS_API_KEY"

   Copy{
     "user_id": "a059c6f4-604d-4f68-81f6-f839b9c95b0a",
     "plan": "weekly",
     "credits_remaining": 281,
     "permissions": {
       "render": true,
       "read": true
     }
   }

2. 2 · Choose a look

   Pick a template by best_for and avoid_for, never by name — the wrong look is the most common way an API-made film disappoints.

   Copycurl https://api.storiasai.com/v1/templates \
     -H "Authorization: Bearer $STORIAS_API_KEY"

   Copy{
     "templates": [
       {
         "id": "newsroom",
         "name": "Newsroom",
         "tier": "pro",
         "description": "Broadcast clarity: fast captions, decisive cuts and a clean lower third. The default when someone is talking to camera and the words carry the piece.",
         "best_for": [
           "talking-head updates",
           "news commentary",
           "announcements",
           "quick explainers"
         ],
         "avoid_for": [
           "silent footage",
           "product beauty shots",
           "long-form documentary"
         ],
         "aspect_ratios": [
           "9:16"
         ],
         "preview_url": "https://edit.storiasai.com/previews/newsroom.mp4"
       },
       {
         "id": "scrapbook",
         "name": "Scrapbook",
         "tier": "pro",
         "description": "Tactile layers, paper cutouts and handwritten notes around the speaker. Warm and personal rather than corporate.",
         "best_for": [
           "personal stories",
           "travel diaries",
           "behind the scenes",
           "community updates"
         ],
         "avoid_for": [
           "financial reporting",
           "formal corporate communication",
           "technical documentation"
         ],
         "aspect_ratios": [
           "9:16"
         ],
         "preview_url": "https://edit.storiasai.com/previews/scrapbook.mp4"
       }
     ]
   }

3. 3 · Upload the clip

   Ask for a one-time URL, then PUT the file to it with the same Content-Type you declared. Already have a link instead? Skip straight to step 4 with video_url.

   Copycurl https://api.storiasai.com/v1/uploads \
     -H "Authorization: Bearer $STORIAS_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"content_type":"video/mp4"}'

   Copy{
     "asset_id": "a059c6f4-604d-4f68-81f6-f839b9c95b0a/7afc924f-a906-4b3f-928c-5a36bed8a6fe.mp4",
     "upload_url": "https://swpjvbgpnqbprqtbaksk.supabase.co/storage/v1/object/upload/sign/uploads/example.mp4?token=example",
     "method": "PUT",
     "headers": {
       "content-type": "video/mp4"
     },
     "expires_in": 7200
   }

   Copycurl -X PUT "$UPLOAD_URL" \
     -H "Content-Type: video/mp4" \
     --data-binary @clip.mp4

4. 4 · Start the render

   Always send Idempotency-Key — a UUID you generate — so retrying this exact call after a timeout returns the same film instead of starting, and charging for, a second one.

   Copycurl https://api.storiasai.com/v1/renders \
     -H "Authorization: Bearer $STORIAS_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{"video_url":"https://example.com/talk.mp4","template_id":"newsroom","aspect_ratio":"9:16"}'

   Copy{
     "render_id": "3f1c1f6e-6a1b-4a1e-9f0a-2b7c9d5e8a10",
     "status": "queued"
   }

5. 5 · Poll for the finished film

   Check back about every ten seconds until status is completed or failed — both are final, and progress never reaches 100 before completed.

   Copycurl https://api.storiasai.com/v1/renders/3f1c1f6e-6a1b-4a1e-9f0a-2b7c9d5e8a10 \
     -H "Authorization: Bearer $STORIAS_API_KEY"

   Copy{
     "render_id": "3f1c1f6e-6a1b-4a1e-9f0a-2b7c9d5e8a10",
     "status": "completed",
     "progress": 100,
     "output": {
       "video_url": "https://remotionlambda-uswest2.s3.us-west-2.amazonaws.com/renders/n0fecl6yho/out.mp4?X-Amz-Signature=example",
       "download_url": "https://remotionlambda-uswest2.s3.us-west-2.amazonaws.com/renders/n0fecl6yho/out.mp4?response-content-disposition=attachment&X-Amz-Signature=example",
       "expires_in": 7200,
       "duration_seconds": 20,
       "aspect_ratio": "9:16"
     },
     "credits_used": 20,
     "template_id": "newsroom"
   }

Authentication

Getting a key

Open Settings → API keys in the web app, signed in on an active plan, and create a key. The key is shown once — Storias stores only its hash, so a lost key is replaced, never recovered. Send it as Authorization: Bearer storias_sk_live_… on every call. Treat it like a payment instrument: it spends real credits, so keep it on a server and out of any code a browser downloads.

Reference

Endpoints

Every path this API serves, with its fields, straight from the live spec.

Copy{
  "templates": [
    {
      "id": "newsroom",
      "name": "Newsroom",
      "tier": "pro",
      "description": "Broadcast clarity: fast captions, decisive cuts and a clean lower third. The default when someone is talking to camera and the words carry the piece.",
      "best_for": [
        "talking-head updates",
        "news commentary",
        "announcements",
        "quick explainers"
      ],
      "avoid_for": [
        "silent footage",
        "product beauty shots",
        "long-form documentary"
      ],
      "aspect_ratios": [
        "9:16"
      ],
      "preview_url": "https://edit.storiasai.com/previews/newsroom.mp4"
    },
    {
      "id": "scrapbook",
      "name": "Scrapbook",
      "tier": "pro",
      "description": "Tactile layers, paper cutouts and handwritten notes around the speaker. Warm and personal rather than corporate.",
      "best_for": [
        "personal stories",
        "travel diaries",
        "behind the scenes",
        "community updates"
      ],
      "avoid_for": [
        "financial reporting",
        "formal corporate communication",
        "technical documentation"
      ],
      "aspect_ratios": [
        "9:16"
      ],
      "preview_url": "https://edit.storiasai.com/previews/scrapbook.mp4"
    }
  ]
}

Copy{
  "content_type": "video/mp4"
}

Copy{
  "asset_id": "a059c6f4-604d-4f68-81f6-f839b9c95b0a/7afc924f-a906-4b3f-928c-5a36bed8a6fe.mp4",
  "upload_url": "https://swpjvbgpnqbprqtbaksk.supabase.co/storage/v1/object/upload/sign/uploads/example.mp4?token=example",
  "method": "PUT",
  "headers": {
    "content-type": "video/mp4"
  },
  "expires_in": 7200
}

Copy{
  "renders": [
    {
      "render_id": "3f1c1f6e-6a1b-4a1e-9f0a-2b7c9d5e8a10",
      "status": "completed",
      "template_id": "newsroom",
      "aspect_ratio": "9:16",
      "duration_seconds": 20,
      "credits_used": 20,
      "created_at": "2026-09-29T14:00:11.000Z",
      "finished_at": "2026-09-29T14:03:02.000Z",
      "output": {
        "video_url": "https://example.r2.cloudflarestorage.com/storias-films/films/example.mp4?X-Amz-Signature=example",
        "download_url": "https://example.r2.cloudflarestorage.com/storias-films/films/example.mp4?response-content-disposition=attachment&X-Amz-Signature=example",
        "expires_in": 7200
      }
    },
    {
      "render_id": "9d0e5c2a-4b8f-4e21-8a63-1f7c3b5d9e02",
      "status": "processing",
      "template_id": "scrapbook",
      "aspect_ratio": "9:16",
      "duration_seconds": 35,
      "credits_used": null,
      "created_at": "2026-09-29T14:10:40.000Z",
      "finished_at": null
    }
  ],
  "next_cursor": null
}

Copy{
  "video_url": "https://example.com/talk.mp4",
  "template_id": "newsroom",
  "aspect_ratio": "9:16"
}

Copy{
  "asset_id": "a059c6f4-604d-4f68-81f6-f839b9c95b0a/7afc924f-a906-4b3f-928c-5a36bed8a6fe.mp4",
  "template_id": "newsroom",
  "aspect_ratio": "9:16"
}

Copy{
  "video_url": "https://example.com/walkthrough.mp4",
  "template_id": "caption-kinetic",
  "aspect_ratio": "9:16",
  "options": {
    "clip_art": true,
    "colors": {
      "accent": "#FFD24A"
    }
  }
}

Copy{
  "render_id": "3f1c1f6e-6a1b-4a1e-9f0a-2b7c9d5e8a10",
  "status": "queued"
}

Copy{
  "render_id": "3f1c1f6e-6a1b-4a1e-9f0a-2b7c9d5e8a10",
  "status": "processing",
  "progress": 62
}

Copy{
  "render_id": "3f1c1f6e-6a1b-4a1e-9f0a-2b7c9d5e8a10",
  "status": "completed",
  "progress": 100,
  "output": {
    "video_url": "https://remotionlambda-uswest2.s3.us-west-2.amazonaws.com/renders/n0fecl6yho/out.mp4?X-Amz-Signature=example",
    "download_url": "https://remotionlambda-uswest2.s3.us-west-2.amazonaws.com/renders/n0fecl6yho/out.mp4?response-content-disposition=attachment&X-Amz-Signature=example",
    "expires_in": 7200,
    "duration_seconds": 20,
    "aspect_ratio": "9:16"
  },
  "credits_used": 20,
  "template_id": "newsroom"
}

Copy{
  "render_id": "3f1c1f6e-6a1b-4a1e-9f0a-2b7c9d5e8a10",
  "status": "failed",
  "progress": 0,
  "error": {
    "code": "RENDER_FAILED",
    "message": "We couldn't finish step 3 of 5.",
    "reference": "Green 7F3A"
  }
}

Copy{
  "user_id": "a059c6f4-604d-4f68-81f6-f839b9c95b0a",
  "plan": "weekly",
  "credits_remaining": 281,
  "permissions": {
    "render": true,
    "read": true
  }
}

Copy{
  "film_id": "8c2d7a4e-1f0b-4c6e-9a3d-5b7e2f1c0a94",
  "render_id": "8c2d7a4e-1f0b-4c6e-9a3d-5b7e2f1c0a94",
  "title": "Harvest report: the Huila microlot",
  "template_id": "newsroom",
  "aspect_ratio": "9:16",
  "duration_seconds": 94.2,
  "finished_at": "2026-09-25T14:03:11.000Z",
  "brand": {
    "id": "4a1f9e2c-7b3d-4e8a-a6c5-0d9f8e7b6a21",
    "name": "Acme Coffee"
  },
  "status": "completed",
  "output": {
    "video_url": "https://remotionlambda-uswest2.s3.us-west-2.amazonaws.com/renders/n0fecl6yho/out.mp4?X-Amz-Signature=example",
    "download_url": "https://remotionlambda-uswest2.s3.us-west-2.amazonaws.com/renders/n0fecl6yho/out.mp4?response-content-disposition=attachment&X-Amz-Signature=example",
    "expires_in": 7200
  }
}

Copy{
  "film_id": "8c2d7a4e-1f0b-4c6e-9a3d-5b7e2f1c0a94",
  "render_id": "8c2d7a4e-1f0b-4c6e-9a3d-5b7e2f1c0a94",
  "title": "Harvest report: the Huila microlot",
  "template_id": "newsroom",
  "aspect_ratio": "9:16",
  "duration_seconds": 94.2,
  "finished_at": null,
  "brand": {
    "id": "4a1f9e2c-7b3d-4e8a-a6c5-0d9f8e7b6a21",
    "name": "Acme Coffee"
  },
  "status": "processing"
}

Reference

Objects

The shapes above, consolidated — useful when you already know the endpoint and just need a field.

Renders

Statuses and polling

A render's status is one of queued, processing, completed, failed. Only completed and failed are final; poll GET /v1/renders/{render_id} about every ten seconds until you see one of them, and never treat a progress of 99 as done. On completed, output.video_url and output.download_url are signed and expire in 2 hours — download the file rather than storing the link. On failed, error.reference is a word and four characters (for example Green 7F3A): show it to whoever hit the failure, since it is what support uses to find the exact film. A failed film is never charged.

Billing

Credits

One credit buys one second of finished film, with a minimum of 15 credits per render. The cost is held on the account when the render is admitted, and charged for real only on delivery. A render that fails instead is never charged, and its hold is released.

Limits

Plans and rate limits

Plan ceilings come from the same contract the apps enforce; a key inherits its account’s plan.

A rate-limited or too-many-renders refusal carries retry_after seconds in the body and in the Retry-After header. It is never charged.

When it says no

Errors

Branch on code, never on message — the wording can improve, the code cannot change. Every response, success or failure, carries an X-Request-Id header.

AI assistants

Connect over MCP

Claude, ChatGPT and most agent frameworks can use Storias as five tools over one JSON-RPC (MCP) endpoint, authenticated with the same key as the REST API:

CopyPOST https://swpjvbgpnqbprqtbaksk.supabase.co/functions/v1/mcp
Authorization: Bearer $STORIAS_API_KEY
Content-Type: application/json

Send the standard MCP handshake (initialize, then tools/list or tools/call) as JSON-RPC 2.0 request bodies. In Claude Desktop or Claude Code, add it as a custom connector with that URL and an Authorization header carrying the same bearer key described above; any MCP-compatible client works the same way.

A tool's failure comes back as a normal result with isError set, carrying a sentence the model can act on (for example, exactly how many credits are missing) — not a protocol error. make_film is safe to retry: calling it again with the same video and look within the hour returns the film already being made rather than starting a second one; after that hour the same call starts, and charges for, a new film. A film that failed was not charged and can be started again. A finished film is final: there is no edit or re-cut.