Get Started with the Varo Cloud API

This guide walks you through everything you need to make your first authenticated request to the Varo Cloud API — from generating a key to running a model and getting back a result.

Base URL: https://inference.varo.cloud/v1 — all endpoints in this guide are relative to it.

Prerequisites

Before you start, make sure you have:

A Varo Cloud account

An API key

Generate an sk_live_ key from your dashboard. You’ll pass it as a Bearer token on every request.

curl or a language runtime

Any HTTP client works. Examples below use curl, Node.js, and Python.

5 minutes

That’s all it takes to go from zero to your first generated asset.

Step 1: Generate an API Key

All requests to the Varo Cloud API are authenticated with a bearer token. To create one:

Open the dashboard

Create a new key

Click Create Key and give it a descriptive name (e.g. local-dev or ci-pipeline).

Copy and store it securely

The full key is shown only once. Copy it immediately and store it in a secret manager or environment variable — never commit it to source control.

export VARO_API_KEY="sk_live_..."

Treat your API key like a password. If a key is ever exposed, delete it from the dashboard and create a new one right away.

Step 2: Create a Generation

Let’s create an image. Send a POST request to /v1/generations with the model you want to run and its inputs. Pass your key in the Authorization header as a bearer token. Generations run asynchronously: this request creates a task and returns immediately with an id and a status. You’ll poll that id in the next step to get the finished asset.

curl -X POST https://inference.varo.cloud/v1/generations \
  -H "Authorization: Bearer $VARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google-nano-banana-pro/text-to-image",
    "prompt": "a cat sitting on a windowsill, golden hour lighting, photorealistic",
    "aspect_ratio": "4:3",
    "output_format": "jpeg",
    "resolution": "1K"
  }'

const response = await fetch("https://inference.varo.cloud/v1/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VARO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "google-nano-banana-pro/text-to-image",
    prompt: "a cat sitting on a windowsill, golden hour lighting, photorealistic",
    aspect_ratio: "4:3",
    output_format: "jpeg",
    resolution: "1K",
  }),
});

const generation = await response.json();
console.log(generation.id, generation.status);

import os
import requests

response = requests.post(
    "https://inference.varo.cloud/v1/generations",
    headers={
        "Authorization": f"Bearer {os.environ['VARO_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "google-nano-banana-pro/text-to-image",
        "prompt": "a cat sitting on a windowsill, golden hour lighting, photorealistic",
        "aspect_ratio": "4:3",
        "output_format": "jpeg",
        "resolution": "1K",
    },
)

generation = response.json()
print(generation["id"], generation["status"])

Step 3: Poll for the Result

Fetch the generation by its id and keep polling until its status becomes completed (or succeeded). If it comes back failed, stop and read the error message.

# Poll until status is completed or succeeded
while true; do
  response=$(curl -s https://inference.varo.cloud/v1/generations/$GENERATION_ID \
    -H "Authorization: Bearer $VARO_API_KEY")
  status=$(echo "$response" | jq -r '.status')
  if [ "$status" = "completed" ] || [ "$status" = "succeeded" ]; then
    echo "$response" | jq -r '.output.url'
    break
  fi
  if [ "$status" = "failed" ]; then
    echo "$response" | jq -r '.error.message // "Generation failed"' >&2
    exit 1
  fi
  sleep 5
done

async function pollGeneration(id) {
  while (true) {
    const res = await fetch(
      `https://inference.varo.cloud/v1/generations/${id}`,
      { headers: { Authorization: `Bearer ${process.env.VARO_API_KEY}` } }
    );
    const generation = await res.json();

    if (["completed", "succeeded"].includes(generation.status)) {
      return generation.output.url;
    }
    if (generation.status === "failed") {
      throw new Error(generation.error?.message ?? "Generation failed");
    }
    await new Promise((r) => setTimeout(r, 5000));
  }
}

console.log(await pollGeneration(generation.id));

import time

def poll_generation(generation_id):
    while True:
        res = requests.get(
            f"https://inference.varo.cloud/v1/generations/{generation_id}",
            headers={"Authorization": f"Bearer {os.environ['VARO_API_KEY']}"},
        )
        generation = res.json()

        if generation["status"] in ("completed", "succeeded"):
            return generation["output"]["url"]
        if generation["status"] == "failed":
            raise RuntimeError(generation.get("error", {}).get("message", "Generation failed"))
        time.sleep(5)

print(poll_generation(generation["id"]))

Poll every few seconds rather than in a tight loop. Image models usually finish in seconds; video models can take longer.

Step 4: Read the Response

The API returns a generation object. When status is completed, output.url points to your finished asset:

{
  "id": "9d481365-2b49-4e94-ac9b-c3d2db5b2374",
  "object": "generation",
  "status": "completed",
  "model": "google-nano-banana-pro/text-to-image",
  "created_at": 1783996705,
  "output": {
    "type": "image",
    "url": "https://cdn.example.com/generations/.../result.jpeg"
  },
  "usage": {
    "cost_usd": 0.04
  }
}

Field	Description
`id`	Unique identifier for this generation
`status`	Generation state — `completed` when the asset is ready
`model`	The model that produced the output
`output.type`	`image` or `video`, depending on the model
`output.url`	Direct link to download the generated asset
`usage.cost_usd`	Cost of this generation, in USD (varies by model and parameters)

If you get back a 401 Unauthorized, double-check that your key is correct, starts with sk_live_, and hasn’t been revoked. See Errors for the full list of response codes.

Step 5: Try Another Model

The same endpoint runs every model on the platform — just change the model field and its inputs. Here’s a video model instead of an image one:

curl -X POST https://inference.varo.cloud/v1/generations \
  -H "Authorization: Bearer $VARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "alibaba-wan-2-7/reference-to-video",
    "prompt": "the cat slowly turns to look at the camera"
  }'

The response has the same shape, with output.type set to video:

{
  "id": "9d481365-2b49-4e94-ac9b-c3d2db5b2374",
  "object": "generation",
  "status": "completed",
  "model": "alibaba-wan-2-7/reference-to-video",
  "created_at": 1783996705,
  "output": {
    "type": "video",
    "url": "https://cdn.example.com/generations/.../result.mp4"
  },
  "usage": {
    "cost_usd": 0.5
  }
}

One API, one key, one response shape for every model — swap the model field to move between image, video, and other modalities without changing your integration.

Next Steps

You’ve run your first model and retrieved a result. Here’s where to go next:

Full API Reference

Browse every endpoint, request schema, and response format.

Authentication Deep Dive

Learn about creating keys, storage, and security best practices.

Errors

Understand error codes and how to handle failed generations.

​Prerequisites

A Varo Cloud account

An API key

curl or a language runtime

5 minutes

​Step 1: Generate an API Key

​Step 2: Create a Generation

​Step 3: Poll for the Result

​Step 4: Read the Response

​Step 5: Try Another Model

​Next Steps

Full API Reference

Authentication Deep Dive

Errors

Prerequisites

Step 1: Generate an API Key

Step 2: Create a Generation

Step 3: Poll for the Result

Step 4: Read the Response

Step 5: Try Another Model

Next Steps