Getting Started

This guide will walk you through your first video render using the Zvid API, from authentication to checking your render status.

Prerequisites

Before you begin, make sure you have:

• ✅ A Zvid account (Sign up here)
• ✅ An API key (Create one in the dashboard)
• ✅ Sufficient credits in your account

Step 1: Verify Your Authentication

First, let's verify that your API key is working by fetching your profile:

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

Expected Response:

{
  "user": {
    "id": 123,
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "created_at": "2025-09-01T00:00:00.000Z"
  },
  "credits": {
    "balance": 1164,
    "subscription_credits": 1164,
    "addon_credits": {
      "balance": 0,
      "total_earned": 0,
      "total_spent": 0
    }
  }
}

Step 2: Check Your Credit Balance

Before rendering, check your credit balance:

curl -X GET https://api.zvid.io/api/credits/balance \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "balance": 1164,
  "subscription_credits": 1164,
  "addon_credits": {
    "balance": 0,
    "total_earned": 0,
    "total_spent": 0
  }
}

Step 3: Submit Your First Render

Let's create a simple 10-second video with text:

curl -X POST https://api.zvid.io/api/render/api-key \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "width": 1920,
      "height": 1080,
      "duration": 10,
      "frameRate": 30,
      "backgroundColor": "#000000",
      "visuals": [
        {
          "type": "TEXT",
          "text": "Hello, Zvid!",
          "x": 960,
          "y": 540,
          "style": {
            "fontSize": 72,
            "color": "#ffffff",
            "fontFamily": "Arial"
          }
        }
      ]
    }
  }'

Response:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "queuePosition": 2,
  "creditsReserved": 15
}

Save the jobId - you'll need it to check the render status!

Understanding the Response

The API response tells you:

• jobId: Unique identifier for your render job
• status: Current status (active, waiting, completed, failed)
• queuePosition: How many jobs are ahead of yours
• creditsReserved: Credits reserved for this render

Step 4: Check Render Status & Get Result

Use the jobId from the previous step to track your render job and retrieve the final video.

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

---

Example Response (Processing)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "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": "550e8400-e29b-41d4-a716-446655440000",
  "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/4/example.mp4",
    "thumbnailUrl": "https://cdn.zvid.io/images/4/example.png",
    "size": 3848989,
    "fileName": "example.mp4",
    "duration": 35.58
  },
  "failedReason": null,
  "ts": {
    "created": 1774290612835,
    "updated": 1774290612835,
    "finished": 1774290629888
  }
}

---

Example Response (Failed)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "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
  }
}

---

How It Works

1. Submit a render job
2. Save the jobId
3. Poll this endpoint every few seconds
4. When state = completed, use result.url
5. If state = failed, check failedReason

💡 Tip: Poll every 2–5 seconds to avoid unnecessary requests.

For more examples and specifications, please head to the documentation page

Error Handling

Always handle errors gracefully:

Validation Error (400)

{
  "error": "Validation failed",
  "message": "Please check your input and try again",
  "details": [
    {
      "field": "payload.duration",
      "message": "Duration must be at least 0.1 seconds"
    }
  ]
}

Solution: Check the validation details, for this example, you can see that the issue with the Duration.

Next Steps

• 📖 Explore the complete Introduction

Need Help?

• Check the FAQ
• Contact us at help@zvid.io