Quickstart

Manage API keys · Create your first video

Make your first request

Create a key with Read permission in API Playground. You must be a member of a workspace with an active paid plan. Your key retains your workspace role. Store the secret on your server. Read the key setup steps.

Use the origin from the First request guide in API Playground. The origin is the address before /api/v1. For example, use https://sovran.ai for the production app or http://localhost:3000 for local development. Use a key from the workspace on that host. Keep SOVRAN_API_KEY in a secret store or server environment variable.

export SOVRAN_API_ORIGIN="https://sovran.ai"
# Set SOVRAN_API_KEY through your secret store.
curl "$SOVRAN_API_ORIGIN/api/v1/projects" \
  -H "Authorization: Bearer $SOVRAN_API_KEY"

A valid key with Read permission returns HTTP 200 when API access is open. An empty workspace returns this response shape. A workspace with projects has project records in data.items.

{
  "data": { "items": [], "nextCursor": null },
  "requestId": "00000000-0000-4000-8000-000000000001"
}

If API Playground shows API access is not available on this host yet, you can prepare keys and webhooks. Requests return 503 with error.code: "api_disabled" until access opens. Some features can also return stage_unavailable. See availability and limits.

Create a finished video

Create your first video has a runnable Node.js example. It uploads two local clips, waits for preparation, creates a sequence, checks the credit estimate, submits one render, and reads the output URL. It keeps the returned IDs and request tokens between steps.

This task needs Read, Write, and Generate permissions. It uses the workspace owner's active paid plan and video render credits. Set a credit limit before you run the example.

Create video drafts

Use the creation guide for Creative Copilot, Smart Variations, Voiceover Remix, and B-roll Remix. These flows save editable drafts. Review each selected draft, check its render estimate, then submit its export. Draft creation does not start an export.

You can use these operations through the API, CLI, or MCP Server. The same source requirements, workspace permissions, paid plan, and charges apply. Check host availability before you submit work.

Choose your next task

• Upload video, music, or images.
• Create and edit content.
• Connect, import, and publish.
• Read job results and handle failures.
• Find an endpoint or response rule.

Webhooks and provider connections are optional for the first request and the first-video example. Connect Meta or TikTok in Account settings before publishing. Connect Google Drive or Dropbox before cloud imports. Read the webhook receiver guide when you want job events on your server.

Use Install CLI + Skill for command-line access and guided agent workflows.

Use MCP Server to connect ChatGPT or Claude. Sign in with Sovran and approve one workspace and its permissions.