title: API Examples slug: /api-examples nav_label: API Examples recommended_nav: true

API Examples

This page collects starter Zvid API examples you can adapt in your backend. Keep API keys server-side and use placeholders such as YOUR_API_KEY in docs, test notes, and support conversations.

Base URL

https://api.zvid.io/api

Verify an API key

Use the profile endpoint to confirm that your key is valid.

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

Check credits

Before submitting a batch of renders, check the current credit balance.

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

Submit a render job

Submit a render job with a top-level payload object.

curl -X POST https://api.zvid.io/api/render/api-key \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "payload": {
      "name": "hello-zvid",
      "resolution": "hd",
      "duration": 6,
      "frameRate": 30,
      "outputFormat": "mp4",
      "backgroundColor": "#08111F",
      "visuals": [
        {
          "type": "TEXT",
          "text": "Hello, Zvid!",
          "x": 640,
          "y": 360,
          "anchor": "center-center",
          "style": {
            "fontSize": 72,
            "color": "#FFFFFF",
            "fontFamily": "Arial"
          }
        }
      ]
    }
  }'

Example queued response:

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

Store the jobId. You will need it to check render status.

Check render status

curl -X GET https://api.zvid.io/api/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"

When the job is complete, use result.url.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "state": "completed",
  "progress": {
    "phase": "uploading",
    "percentage": 100,
    "message": "Uploading to B2: 100%"
  },
  "result": {
    "ok": true,
    "url": "https://cdn.zvid.io/videos/4/hello-zvid.mp4",
    "thumbnailUrl": "https://cdn.zvid.io/images/4/hello-zvid_thumbnail.jpg",
    "duration": 6
  },
  "failedReason": null
}

If the job fails, inspect failedReason, fix the payload or source media, and submit a new render.

JavaScript example

const apiKey = process.env.ZVID_API_KEY;

const submitResponse = await fetch("https://api.zvid.io/api/render/api-key", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": apiKey,
  },
  body: JSON.stringify({
    payload: {
      name: "hello-zvid",
      resolution: "hd",
      duration: 6,
      frameRate: 30,
      outputFormat: "mp4",
      backgroundColor: "#08111F",
      visuals: [
        {
          type: "TEXT",
          text: "Hello, Zvid!",
          x: 640,
          y: 360,
          anchor: "center-center",
          style: {
            fontSize: 72,
            color: "#FFFFFF",
            fontFamily: "Arial",
          },
        },
      ],
    },
  }),
});

const submitted = await submitResponse.json();
const jobId = submitted.jobId;

const statusResponse = await fetch(`https://api.zvid.io/api/jobs/${jobId}`, {
  headers: {
    "x-api-key": apiKey,
  },
});

const job = await statusResponse.json();
console.log(job.state, job.result?.url);

Useful docs

Security reminders

Never expose Zvid API keys in browser code.
Never commit keys to a public repository.
Store keys in server-side environment variables or a secrets manager.
Use separate keys for development and production.
Revoke keys that are unused or suspected to be exposed.

Command Palette