Quickstart — getvivix API Docs

Three steps: get a key, send a request, read the result. The samples below use curl — same shape works in Node, Python, anything that can speak HTTP.

1. Get an API key

Go to Settings → API & Webhooks and click Create new key. Save the plaintext value — it's shown once. Pro and Ultimate tiers only; if you're on Free or Standard you'll see an upgrade prompt instead.

Store the plaintext key somewhere safe (an environment variable, a secrets manager, your CI's vault). We never store it ourselves — we hash it on creation and only the hash hits the database. If you lose it, you create a new one and revoke the old.

2. Send your first request

Pick a model from the models page. For this quickstart we'll use Grok Imagine Image Quality — fast, high-quality 4K stills.

export VIVIX_KEY="vvx_live_..."

curl -X POST https://getvivix.com/api/v1/generate \
  -H "Authorization: Bearer $VIVIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "a misty forest at dawn, cinematic 24mm",
    "aspect_ratio": "16:9",
    "resolution": "4K"
  }'

You'll get back JSON like this — note the generation_id:

{
  "generation_id": "5b91a581-ee19-4f86-9fea-bd29471d69d5",
  "status":           "pending",
  "model":            "grok-imagine-image-quality",
  "credits_estimate": 211,
  "created_at":       "2026-05-10T12:34:56Z"
}

3. Read the result

Poll until status === "completed". Image models finish in ~5–15s, video in ~30–120s depending on duration and resolution. We recommend polling every 2–4s.

curl https://getvivix.com/api/v1/generations/5b91a581-ee19-4f86-9fea-bd29471d69d5 \
  -H "Authorization: Bearer $VIVIX_KEY"

{
  "generation_id": "5b91a581-ee19-4f86-9fea-bd29471d69d5",
  "status":        "completed",
  "model":         "grok-imagine-image-quality",
  "output_url":    "https://pub-364da8d08c644542b169fbc7255349e7.r2.dev/5b91a581-...mp4",
  "credits_used":  211,
  "duration_ms":   12420,
  "completed_at":  "2026-05-10T12:35:08Z"
}

The output_url is a public R2 URL — no auth required to fetch the asset. Copy it, embed it, download it, hand it off to your pipeline.

In your code

Same call, three languages.

NODE.JS

const res = await fetch('https://getvivix.com/api/v1/generate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIVIX_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'grok-imagine-image-quality',
    prompt: 'a misty forest at dawn',
    aspect_ratio: '16:9',
    resolution: '4K',
  }),
})
const { generation_id } = await res.json()

PYTHON

import os, requests

res = requests.post(
    "https://getvivix.com/api/v1/generate",
    headers={
        "Authorization": f"Bearer {os.environ['VIVIX_KEY']}",
        "Content-Type":  "application/json",
    },
    json={
        "model":        "grok-imagine-image-quality",
        "prompt":       "a misty forest at dawn",
        "aspect_ratio": "16:9",
        "resolution":   "4K",
    },
)
generation_id = res.json()["generation_id"]

TYPESCRIPT

type GenerateResponse = {
  generation_id: string
  status: 'pending' | 'processing' | 'completed' | 'failed'
  credits_estimate: number
}

const res = await fetch('https://getvivix.com/api/v1/generate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIVIX_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'grok-imagine-image-quality',
    prompt: 'a misty forest at dawn',
  }),
})
const data = await res.json() as GenerateResponse

Where to next

Browse all models with their params and cost bands
Authentication — key rotation, secret hygiene, IP allowlists
Error codes — what every status code means and how to recover