> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API IA

> Appels IA universels — chat, images, parole, transcription, vidéo — facturés sur votre espace.

L'API IA Kazzle vous donne un seul point de terminaison authentifié pour appeler n'importe quel modèle que nous supportons. Vous payez une seule fois, en crédits, sur votre espace — pas de comptes séparés pour OpenAI, Anthropic, Cloudflare Workers AI, ou quiconque d'autre vers lequel nous routons.

Tous les points de terminaison se trouvent sous `/ai/*` sur `https://api.kazzle.app` et acceptent une clé API `kzl_` dans l'en-tête `Authorization`. Voir [Clés API](/platform/api-keys) pour savoir comment en créer une.

Les applications Kazzle générées doivent aussi utiliser cette API — voir [IA dans les applications](/apps/ai-api) pour intégrer la clé dans un composant. Ne demandez pas aux utilisateurs leurs clés de fournisseur à moins qu'ils ne veuillent explicitement utiliser leur propre compte fournisseur.

## Capacités

| Point de terminaison            | Modalité                 | Entrée standardisée                                   | Sortie standardisée                            |
| ------------------------------- | ------------------------ | ----------------------------------------------------- | ---------------------------------------------- |
| `POST /ai/chat/completions`     | Chat (texte, streaming)  | `messages[]` compatible OpenAI                        | `choices[]` compatible OpenAI ou flux SSE      |
| `POST /ai/responses`            | API Responses            | Compatible OpenAI Responses                           | Compatible OpenAI Responses                    |
| `POST /ai/images/generations`   | Image                    | `{ model, prompt, size?, output_format? }`            | `{ images: [{ url? \| b64?, mimeType }] }`     |
| `POST /ai/audio/speech`         | Synthèse vocale          | `{ model, text, voice?, format? }`                    | flux d'octets `audio/*`                        |
| `POST /ai/audio/transcriptions` | Reconnaissance vocale    | `multipart/form-data` avec `file` + `model`           | `{ text }`                                     |
| `POST /ai/video/generations`    | Vidéo (asynchrone)       | `{ model, prompt, ... }`                              | `{ id, status, pollUrl }`                      |
| `GET  /ai/responses/{id}`       | Interrogation asynchrone | id de réponse                                         | résultat au format fournisseur                 |
| `POST /ai/gateway`              | Passthrough brut         | N'importe quel payload Workers AI / natif fournisseur | Réponse brute en amont                         |
| `GET  /ai/models`               | Catalogue                | —                                                     | `{ models: [{ id, modality, pricing, ... }] }` |

`GET /ai/models` est la source de vérité pour savoir quels identifiants de modèle fonctionnent sur quel point de terminaison. Consultez-le d'abord si vous construisez par rapport à l'API.

## Comment fonctionne un appel

Chaque appel facturable passe par cinq phases. Vous ne voyez pas la plupart d'entre elles — elles sont suivies côté serveur pour que nous puissions rembourser les appels échoués et signaler l'utilisation exacte.

| Phase      | Ce qui s'est passé                                                                                                                |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `open`     | Nous avons créé un événement de facturation lié à votre demande, mais n'avons pas encore appelé en amont.                         |
| `recorded` | Le fournisseur en amont a répondu. Nous avons un identifiant de journal de Cloudflare AI Gateway. Le coût n'est pas encore connu. |
| `priced`   | Cloudflare a signalé le coût final. Nous avons appliqué notre marge et écrit la charge de crédit. Terminal.                       |
| `failed`   | L'appel en amont a échoué, ou nous n'avons pas pu obtenir un coût après 20 tentatives. Le client n'est **pas** facturé. Terminal. |
| `synced`   | L'événement tarifé a été livré à notre système de mesure.                                                                         |

Chaque réponse réussie inclut `x-kazzle-ai-billing-event-id: airesp_...` — conservez-le si vous voulez corréler la demande avec les exports d'utilisation plus tard.

## Facturation et marge

Nous facturons `cloudflare_cost_usd × (1 + markup)`. La marge est publiée dans [Paramètres → Facturation → Tarification](/platform/billing#pricing). Les appels que Cloudflare a tarifés à 0 \$ (niveau gratuit Workers AI, promos) atteignent la phase `priced` avec un coût zéro et ne sont jamais facturés.

Réserve : vous avez besoin d'au moins **0,50 \$** équivalent en crédits pour faire un appel. Nous le maintenons contre votre solde jusqu'à ce que l'appel se termine, puis nous réglons le coût réel.

## Erreurs

| Statut         | Signification                                                                               |
| -------------- | ------------------------------------------------------------------------------------------- |
| `401`          | Clé API `kzl_` manquante ou invalide.                                                       |
| `402`          | Crédits insuffisants pour la réserve. Rechargez dans **Paramètres → Facturation**.          |
| `4xx` en amont | Transféré tel quel. Le corps contient l'erreur du fournisseur. Le client n'est pas facturé. |
| `5xx` en amont | Transféré tel quel. Le client n'est pas facturé.                                            |

## Exemple — génération d'image

```bash theme={"theme":"material-theme-darker"}
curl https://api.kazzle.app/ai/images/generations \
  -H "Authorization: Bearer kzl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-1",
    "prompt": "a single red dot on white",
    "size": "1024x1024"
  }'
```

```json theme={"theme":"material-theme-darker"}
{
  "images": [
    { "url": "https://...", "mimeType": "image/png" }
  ]
}
```

## Exemple — synthèse vocale

```bash theme={"theme":"material-theme-darker"}
curl https://api.kazzle.app/ai/audio/speech \
  -H "Authorization: Bearer kzl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/tts-1","text":"hello world","voice":"alloy","format":"mp3"}' \
  --output speech.mp3
```

## Voir aussi

* [Référence API](/api-reference) — schémas complets de demande/réponse pour chaque point de terminaison
* [Clés API](/platform/api-keys) — création et utilisation des clés `kzl_`
* [Facturation](/platform/billing) — crédits, plans et la marge que nous appliquons