# Premier appel

> Créez une clé sur votre compte Tukai, gardez-la dans une variable d'environnement et envoyez une première requête de texte en quelques minutes.

Source : https://developers.tuk-ai.com/docs/quickstart · Vérifié le 2026-10-04

**Résultat attendu** : une réponse de quelques mots, générée par un modèle du catalogue Tukai, depuis votre propre terminal ou votre propre code.

**Ce qu'il vous faut** : un compte Tukai avec un abonnement actif ou des crédits, et l'un de ces outils : `curl` (macOS, Linux), PowerShell (Windows), ou Node.js / Python avec le SDK officiel `openai` installé.

> **Un appel est payant**
>
> Chaque requête de génération consomme les droits de votre compte Tukai, les mêmes que ceux de l'application. Un compte sans abonnement ni crédit reçoit une erreur `402` et rien n'est débité. Voir [Crédits et facturation](https://developers.tuk-ai.com/docs/billing).

## 1. Créer une clé

1. Ouvrez [chat.tuk-ai.com](https://chat.tuk-ai.com) et connectez-vous.
2. Ouvrez les réglages, groupe **Fournisseurs**, onglet **Clés API**.
3. Donnez un nom à la clé (par exemple `essai-local`) et cochez le modèle `chat-aion-labs-aion-3-0-mini`, utilisé dans les exemples ci-dessous. Fixez si vous le souhaitez un **plafond mensuel** en dinars.
4. Créez la clé et **copiez-la immédiatement** : elle commence par `tuk_sk_` et ne sera plus jamais affichée. Seul son début (préfixe) reste visible ensuite.

Une clé n'appelle que les modèles cochés à sa création : un autre modèle est refusé (`403`), jamais remplacé en silence.

## 2. Garder la clé hors du code

Placez la clé dans une variable d'environnement de votre session. Ne la collez pas dans un fichier versionné.

macOS / Linux :

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

Windows (PowerShell) :

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

## 3. Envoyer la requête

L'URL de base est `https://chat.tuk-ai.com/v1`. La clé passe dans l'en-tête `Authorization: Bearer`.

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)
```

Sous Windows, utilisez l'onglet PowerShell : dans Windows PowerShell 5.1, `curl` désigne une autre commande et l'exemple curl échoue.

Le modèle de ces exemples est le modèle par défaut du catalogue public au moment de la vérification. Tout identifiant de la page [Modèles](https://developers.tuk-ai.com/models) coché sur votre clé fonctionne de la même façon.

## 4. Lire la réponse

Une réponse réussie a cette forme. Le texte généré varie d'un appel à l'autre.

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 }
}
```

Chaque réponse, réussie ou non, porte un en-tête `x-request-id`. Notez-le : c'est ce que le support vous demandera.

## Si ça ne marche pas

| Ce que vous voyez | Cause probable | Que faire |
|---|---|---|
| `401 authentication_error` | Clé absente, mal copiée, révoquée ou expirée | Vérifiez la variable d'environnement ; créez une nouvelle clé si besoin |
| `402 insufficient_quota` | Pas d'abonnement ni de crédit sur le compte | [Rechargez](https://chat.tuk-ai.com/pay/checkout), puis relancez |
| `403 permission_error` | Le plus souvent, le modèle n'est pas coché sur cette clé | Modifiez la clé ou changez de modèle ; voir [Erreurs](https://developers.tuk-ai.com/docs/errors) pour les autres causes |
| `429 rate_limit_error` | Débit de la clé, plafond mensuel de la clé, ou limites d'usage de votre offre | Attendez la fin de la fenêtre (en-têtes `retry-after` et `ratelimit-reset`) ; voir [Erreurs](https://developers.tuk-ai.com/docs/errors) |

Lisez le champ `type` de l'erreur, pas son message : selon la cause, le message est en anglais ou en français.

## Et ensuite

- Vous utilisez déjà le SDK OpenAI ou Anthropic : lisez [Compatibilité](https://developers.tuk-ai.com/docs/compatibility) avant de migrer.
- Vous voulez Claude Code sur votre compte Tukai : [CLI tukai](https://developers.tuk-ai.com/tools/cli).
- Vous préparez une mise en service : [Mise en production](https://developers.tuk-ai.com/docs/production).