Quickstart

Manage API keys · Create your first video

Make your first request

Create a key with Read permission in Developer. You must be a workspace owner or admin with an active paid plan. Store the secret on your server. Read the key setup steps.

Use the origin from the First request guide in Developer. 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 Developer 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.

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 the CLI and agent skill for command-line access and guided agent workflows.

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