Skip to main content

Introduction

Welcome to the Zvid API Documentation! This API allows you to programmatically create and manage video rendering jobs, monitor your credit usage, and manage API keys.

What is Zvid?​

Zvid is a powerful video rendering platform that allows you to create professional videos programmatically. With the Zvid API, you can:

  • 🎬 Render videos with custom visuals, subtitles, text, images, and audio
  • 💳 Manage credits and monitor your usage
  • 🔑 Create and manage API keys for secure access
  • 📊 Track statistics for your rendering jobs
  • 👤 Access your profile and account information

Quick Start​

Get started with the Zvid API in three simple steps:

1. Create an API Key​

First, you'll need to create an API key from the Zvid Dashboard:

  1. Log in to your Zvid account
  2. Click the API Access box at the bottom right corner.
  3. Click Create API Key at the top right corner.
  4. Give your key a descriptive name (e.g., "Production API")
  5. Copy and save the key securely - you won't be able to see it again!

2. Make Your First Request​

Use your API key to make requests to the API:

curl -X GET https://api.zvid.io/api/user/profile \
  -H "x-api-key: your-api-key-here"

3. Start Rendering Videos​

Submit your first render job:

curl -X POST https://api.zvid.io/api/render/api-key \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "name": "test",
      "width": 1920,
      "height": 1080,
      "duration": 10,
      "backgroundColor": "#000000",
      "visuals": [
        {
          "type": "TEXT",
          "text": "Hello, Zvid!",
          "x": 960,
          "y": 540
        }
      ]
    }
  }'

The response will include a render job id. Save this ID so you can check the job status and retrieve the final result.

4. Check Your Render Job Result​

After submitting a render job, use the returned job id to check its status and retrieve the final result.

curl -X GET https://api.zvid.io/api/render/{jobId} \
  -H "x-api-key: your-api-key-here"

Example Response (Processing)​

{
  "id": "a88b7ad5-d0ed-48be-95df-b4ee41f3f07e",
  "state": "active",
  "progress": {
    "phase": "rendering",
    "percentage": 65,
    "message": "Rendering frames..."
  },
  "result": null,
  "failedReason": null,
  "ts": {
    "created": 1774290612835,
    "updated": 1774290615000,
    "finished": null
  }
}

Example Response (Completed)​

{
  "id": "a88b7ad5-d0ed-48be-95df-b4ee41f3f07e",
  "state": "completed",
  "progress": {
    "phase": "uploading",
    "percentage": 100,
    "message": "Uploading to B2: 100%"
  },
  "result": {
    "ok": true,
    "renderDuration": 16,
    "totalDuration": 17,
    "finishedAt": "2026-03-23T18:30:29.888Z",
    "url": "https://cdn.zvid.io/videos/121/test.mp4",
    "thumbnailUrl": "https://cdn.zvid.io/images/121/test.png",
    "size": 3848989,
    "fileName": "test.mp4",
    "duration": 35.58333333333333
  },
  "failedReason": null,
  "ts": {
    "created": 1774290612835,
    "updated": 1774290612835,
    "finished": 1774290629888
  }
}

Example Response (Failed)​

{
  "id": "a88b7ad5-d0ed-48be-95df-b4ee41f3f07e",
  "state": "failed",
  "progress": {
    "phase": "rendering",
    "percentage": 40,
    "message": "Processing failed"
  },
  "result": null,
  "failedReason": "Rendering failed due to invalid asset",
  "ts": {
    "created": 1774290612835,
    "updated": 1774290617000,
    "finished": 1774290617000
  }
}

Response Fields​

  • id: The render job ID
  • state: Current job state (waiting, active, completed, failed)
  • progress: Detailed progress information
    • phase: Current stage (e.g., rendering, uploading)
    • percentage: Progress (0–100)
    • message: Human-readable status
  • result: Final render output (only present when completed)
    • ok: Indicates success
    • url: Final video URL
    • thumbnailUrl: Preview image
    • fileName: Output file name
    • size: File size in bytes
    • duration: Video duration (seconds)
    • renderDuration: Time spent rendering (seconds)
    • totalDuration: Total processing time (seconds)
    • finishedAt: Completion timestamp
  • failedReason: Error message if the job failed
  • ts: Timestamps
    • created: Job creation time
    • updated: Last update time
    • finished: Completion or failure time

Typical Workflow​

  1. Submit a render job
  2. Store the returned job id
  3. Poll the job status endpoint
  4. When state = completed, use result.url
  5. When state = failed, inspect failedReason

What's Next?​

Need Help?​

API Base URL​

All API requests should be made to:

https://api.zvid.io/api