# Quickstart

> Create an API key and make your first request with curl, Python or Node.js.

## 1. Create an account and an API key

1.  [Sign up](https://clonvo.com/sign-up) and verify your email address. You get a personal organization on the [Free plan](https://clonvo.com/docs/plans.md), with its own credit balance.
2.  Open **API keys** and create a key. Copy it straight away: the full key is shown only once.
3.  Choose how to make your first request:
    -   **Buy credits** on the **Credits** page, from $5. Any purchase moves your organization to Pay as you go, which unlocks every model and lets you [bring your own provider keys](https://clonvo.com/docs/byok.md).
    -   **Or start free** with a [free model](https://clonvo.com/docs/free-models.md): an owner or admin turns on **Use free models** in **Settings → Privacy** and accepts its data terms, then use a model id ending in `:free`.

> **Note: Paid models need credits**
> 
> On Free, requests to paid models such as `openai/gpt-6.1-sol` fail with `402` and the code `insufficient_credits` until you buy credits. The examples below use a paid model; [A zero-cost first request](#a-zero-cost-first-request) shows the free option.

Keys look like `sk-cv-v1-` followed by 64 hexadecimal characters. Store yours in an environment variable:

```bash
export CLONVO_API_KEY="sk-cv-v1-…"
```

> **Warning**
> 
> Treat API keys like passwords. Don’t commit them to source control or ship them in browser or mobile apps. If a key leaks, revoke it in the dashboard and create a new one.

## 2. Make a request

Clonvo is OpenAI-compatible, so you can use the official OpenAI SDKs. Set the base URL to `https://api.clonvo.com/v1` and pick any model id from the [catalogue](https://clonvo.com/models.md).

### curl

```bash
curl https://api.clonvo.com/v1/chat/completions \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6.1-sol",
    "messages": [{"role": "user", "content": "Write a haiku about routers."}]
  }'
```

### Python

Install the SDK with `pip install openai`.

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.clonvo.com/v1",
    api_key=os.environ["CLONVO_API_KEY"],
)

completion = client.chat.completions.create(
    model="openai/gpt-6.1-sol",
    messages=[{"role": "user", "content": "Write a haiku about routers."}],
)
print(completion.choices[0].message.content)
```

### Node.js

Install the SDK with `npm install openai`.

```js
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.clonvo.com/v1",
  apiKey: process.env.CLONVO_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "openai/gpt-6.1-sol",
  messages: [{ role: "user", content: "Write a haiku about routers." }],
});
console.log(completion.choices[0].message.content);
```

### A zero-cost first request

On Free, swap in a free model. Free model ids change as OpenRouter adds and removes them, so pick one from the list:

```bash
curl -s https://api.clonvo.com/v1/models | jq -r '.data[].id | select(endswith(":free"))'
```

Then send it in `model`, exactly as listed:

```bash
curl https://api.clonvo.com/v1/chat/completions \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<author>/<model>:free",
    "messages": [{"role": "user", "content": "Write a haiku about routers."}]
  }'
```

Free models cost $0 and allow 20 requests a minute and 50 a day. See [Free models](https://clonvo.com/docs/free-models.md) for the limits and what to expect from free endpoints.

## 3. Read the response

The response is a standard Chat Completions object. Clonvo adds a `provider` field (the display name of the provider that served the request) and reports the cost in `usage.cost` (US dollars at list price). `model` is the canonical id of the model that answered.

```json
{
  "id": "gen-01M67FGKKVQ8ZK2M3N5P7R9S1V",
  "object": "chat.completion",
  "created": 1793400000,
  "model": "openai/gpt-6.1-sol",
  "provider": "OpenAI",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Packets find their way…" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 19,
    "total_tokens": 33,
    "prompt_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 },
    "cost": 0.000218,
    "is_byok": false
  }
}
```

## 4. Switch models

Change the `model` string. Nothing else in the request needs to change:

```python
for model in ["anthropic/claude-sonnet-5-5", "google/gemini-3.8-flash", "x-ai/grok-4-7"]:
    completion = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": "Write a haiku about routers."}],
    )
    print(model, completion.choices[0].message.content)
```

## Next steps

-   Stream tokens as they’re generated: [Streaming](https://clonvo.com/docs/streaming.md).
-   Let the model call your functions: [Tool calling](https://clonvo.com/docs/tool-calling.md).
-   Keep requests working when a provider is having trouble: [Fallbacks and routing](https://clonvo.com/docs/fallbacks.md).