# First call

> Create a key on your Tukai account, keep it in an environment variable, and send a first text request in a few minutes.

Source : https://developers.tuk-ai.com/en/docs/quickstart · Verified on 2026-10-04

**Expected result**: a reply of a few words, generated by a model from the Tukai catalog, from your own terminal or your own code.

**What you need**: a Tukai account with an active subscription or credits, and one of these tools: `curl` (macOS, Linux), PowerShell (Windows), or Node.js / Python with the official `openai` SDK installed.

> **A call is not free**
>
> Each generation request uses your Tukai account's entitlements, the same ones as the app. An account with no subscription and no credits receives a `402` error and nothing is charged. See [Credits and billing](https://developers.tuk-ai.com/en/docs/billing).

## 1. Create a key

1. Open [chat.tuk-ai.com](https://chat.tuk-ai.com) and sign in.
2. Open the settings, group **Fournisseurs** (Providers), tab **Clés API** (API keys).
3. Give the key a name (for example `essai-local`) and tick the model `chat-aion-labs-aion-3-0-mini`, used in the examples below. If you wish, set a **monthly cap** in dinars.
4. Create the key and **copy it immediately**: it starts with `tuk_sk_` and will never be shown again. Only its beginning (prefix) remains visible afterwards.

A key can only call the models ticked when it was created: any other model is refused (`403`), never silently replaced.

## 2. Keep the key out of your code

Put the key in an environment variable for your session. Do not paste it into a version-controlled file.

macOS / Linux :

```bash
export TUKAI_API_KEY="collez-votre-cle-ici"
```

Windows (PowerShell) :

```powershell
$env:TUKAI_API_KEY = "collez-votre-cle-ici"
```

## 3. Send the request

The base URL is `https://chat.tuk-ai.com/v1`. The key goes in the `Authorization: Bearer` header.

curl (macOS / Linux) :

```bash
curl https://chat.tuk-ai.com/v1/chat/completions \
  -H "Authorization: Bearer $TUKAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chat-aion-labs-aion-3-0-mini",
    "max_tokens": 100,
    "messages": [{ "role": "user", "content": "Donne en une phrase la capitale de la Tunisie." }]
  }'
```

PowerShell :

```powershell
$corps = @{
  model      = "chat-aion-labs-aion-3-0-mini"
  max_tokens = 100
  messages   = @(@{ role = "user"; content = "Donne en une phrase la capitale de la Tunisie." })
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Method Post -Uri "https://chat.tuk-ai.com/v1/chat/completions" `
  -Headers @{ Authorization = "Bearer $env:TUKAI_API_KEY" } `
  -ContentType "application/json; charset=utf-8" `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($corps))
```

TypeScript :

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://chat.tuk-ai.com/v1",
  apiKey: process.env.TUKAI_API_KEY,
});

const reponse = await client.chat.completions.create({
  model: "chat-aion-labs-aion-3-0-mini",
  max_tokens: 100,
  messages: [{ role: "user", content: "Donne en une phrase la capitale de la Tunisie." }],
});

console.log(reponse.choices[0].message.content);
```

Python :

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://chat.tuk-ai.com/v1",
    api_key=os.environ["TUKAI_API_KEY"],
)

reponse = client.chat.completions.create(
    model="chat-aion-labs-aion-3-0-mini",
    max_tokens=100,
    messages=[{"role": "user", "content": "Donne en une phrase la capitale de la Tunisie."}],
)

print(reponse.choices[0].message.content)
```

On Windows, use the PowerShell tab: in Windows PowerShell 5.1, `curl` refers to a different command and the curl example fails.

The model in these examples is the default model of the public catalog at the time of verification. Any identifier from the [Models](https://developers.tuk-ai.com/models) (French) page that is ticked on your key works the same way.

## 4. Read the response

A successful response looks like this. The generated text varies from one call to the next.

Réponse :

```json
{
  "id": "…",
  "object": "chat.completion",
  "created": 1790000000,
  "model": "chat-aion-labs-aion-3-0-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "La capitale de la Tunisie est Tunis." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 18, "completion_tokens": 9, "total_tokens": 27 }
}
```

Every response, successful or not, carries an `x-request-id` header. Write it down: it is what support will ask you for.

## If it does not work

| What you see | Likely cause | What to do |
|---|---|---|
| `401 authentication_error` | Key missing, miscopied, revoked or expired | Check the environment variable; create a new key if needed |
| `402 insufficient_quota` | No subscription and no credits on the account | [Top up](https://chat.tuk-ai.com/pay/checkout), then retry |
| `403 permission_error` | Most often, the model is not ticked on this key | Edit the key or change the model; see [Errors](https://developers.tuk-ai.com/en/docs/errors) for other causes |
| `429 rate_limit_error` | Key rate limit, key monthly cap, or your plan's usage limits | Wait for the window to end (`retry-after` and `ratelimit-reset` headers); see [Errors](https://developers.tuk-ai.com/en/docs/errors) |

Read the error's `type` field, not its message: depending on the cause, the message is in English or in French.

## Next steps

- You already use the OpenAI or Anthropic SDK: read [Compatibility](https://developers.tuk-ai.com/en/docs/compatibility) before migrating.
- You want Claude Code on your Tukai account: [tukai CLI](https://developers.tuk-ai.com/tools/cli) (French).
- You are preparing to go live: [Going to production](https://developers.tuk-ai.com/en/docs/production).