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",
    "email_verified": true,
    "created_at": "2025-09-01T00:00:00.000Z"
  },
  "credits": {
    "balance": 1800,
    "reserved": 0,
    "available": 1800
  }
}

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": 1000,
  "reserved": 0,
  "available": 1000
}

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!

Step 4: 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

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 and correct your request.

Next Steps

• 📖 Explore the complete API Reference

Need Help?

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