API

Early Access

Cette fonctionnalité est actuellement en phase d'early access.
Au vue de la demande nous ouvrons les places au fur et à mesure.
Contactez-nous ici pour être inscrit sur la liste d'attente.

L'API de conversation est accessible à l'adresse POST /api/chat.

Elle s'appuie autant que possible sur le format de la Responses API d'OpenAI : objets message, contenus input_text et output_text, réponses et événements SSE response.*. L'enveloppe de requête Haloon reste toutefois spécifique : elle utilise thread_id, model et messages au lieu de input.

Sécurité

Chaque appel à /api/* doit inclure la clé qui vous a été fournie. Le format est :

http

Authorization: Bearer ak-votre_cle

Ajoutez également cet en-tête à tous les appels qui modifient l'état, dont POST /api/chat :

http

Csrf-Token: nocheck

Haloon applique la protection CSRF aux requêtes HTTP. Cette protection est nécessaire pour les sessions web fondées sur des cookies, mais un client d'API s'authentifie avec une clé Bearer et ne dispose pas de jeton de session CSRF. Csrf-Token: nocheck active le bypass prévu pour ces clients ; il ne remplace pas l'authentification par clé d'API et ne doit pas être considéré comme un mécanisme de sécurité.

La clé commence par ak-. Ne l'exposez jamais dans du code frontend, un dépôt Git, une URL ou des journaux. Stockez-la dans une variable d'environnement ou un gestionnaire de secrets. Une clé absente, mal formée ou inconnue n'authentifie pas la requête.

bash

export HALOON_API_KEY='ak-votre_cle'

Créer une conversation avec un LLM

Le paramètre messages reprend les éléments d'entrée de la Responses API d'OpenAI. Pour du texte, envoyez un objet message contenant un input_text.

Créer un `thread_id`

Un thread_id est requis. Le format canonique est thd-<uuid>, par exemple thd-550e8400-e29b-41d4-a716-446655440000.

Le comportement dépend de sa valeur :

Si vous transmettez un thread_id existant, le message est ajouté à cette conversation.
Si vous transmettez un nouvel identifiant au format thd-<uuid>, le thread est créé automatiquement avec cet identifiant. C'est le cas recommandé : vous connaissez immédiatement l'identifiant à réutiliser.
Si vous transmettez une autre chaîne, un thread est également créé automatiquement, mais avec un thread_id aléatoire au format attendu. Cet identifiant n'est pas renvoyé par POST /api/chat.

Générez donc de préférence l'identifiant côté client avant le premier appel, puis réutilisez-le pour chaque tour.

Envoyer le premier message

L'exemple suivant désactive le streaming afin de recevoir un unique objet JSON de type Responses API.

bash

curl --request POST "https://haloon.ai/api/chat" \
  --header "Authorization: Bearer $HALOON_API_KEY" \
  --header 'Csrf-Token: nocheck' \
  --header 'Content-Type: application/json' \
  --data '{
    "thread_id": "'"$THREAD_ID"'",
    "model": "gpt-fast",
    "stream": false,
    "messages": [
      {
        "type": "message",
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Bonjour, peux-tu me raconter une blague ?" }
        ]
      }
    ]
  }'

La réponse suit la structure d'une réponse OpenAI : elle contient notamment id, status, model, output et, lorsqu'ils sont disponibles, usage et error.

Répondre dans la même conversation

Réutilisez le même thread_id et renvoyez l'historique utile. Le message assistant précédent utilise le format OpenAI output_text, puis le nouveau message utilisateur utilise input_text.

bash

curl --request POST "https://haloon.ai/api/chat" \
  --header "Authorization: Bearer $HALOON_API_KEY" \
  --header 'Csrf-Token: nocheck' \
  --header 'Content-Type: application/json' \
  --data '{
    "thread_id": "'"$THREAD_ID"'",
    "model": "gpt-fast",
    "stream": false,
    "messages": [
      {
        "type": "message",
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Bonjour, peux-tu me raconter une blague ?" }
        ]
      },
      {
        "type": "message",
        "role": "assistant",
        "status": "completed",
        "content": [
          { "type": "output_text", "text": "Bien sûr — en voilà une courte :\n\nPourquoi les plongeurs plongent-ils toujours en arrière et jamais en avant ?\n\nParce que s’ils plongeaient en avant, ils tomberaient encore dans le bateau !" }
        ]
      },
      {
        "type": "message",
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Je la connais deja, une autre stp" }
        ]
      }
    ]
  }'

Pour recevoir la réponse progressivement, omettez stream ou définissez-le à true, puis ajoutez --no-buffer à curl. La réponse est alors un flux SSE : chaque ligne data: contient un événement au format OpenAI, par exemple response.output_text.delta; le flux se termine par data: [DONE].

bash

curl --no-buffer --request POST "https://haloon.ai/api/chat" \
  --header "Authorization: Bearer $HALOON_API_KEY" \
  --header 'Csrf-Token: nocheck' \
  --header 'Content-Type: application/json' \
  --data '{
    "thread_id": "'"$THREAD_ID"'",
    "model": "gpt-fast",
    "messages": [
      {
        "type": "message",
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Écris une accroche courte." }
        ]
      }
    ]
  }'

Paramètres

Paramètre	Type	Requis	Description
`thread_id`	chaîne	oui	Identifiant stable de la conversation, à réutiliser pour ses tours suivants.
`model`	chaîne	oui	Identifiant d’un modèle prédéfini Haloon, par exemple `gpt-fast`, `gpt-thinking`, `gpt-codex`, `gpt-5.6-sol` ou `gpt-5.6-terra`.
`messages`	tableau	oui	Historique de la conversation, au format d'éléments `message` de la Responses API OpenAI.
`stream`	booléen	non	`true` par défaut : réponse en SSE. Définissez `false` pour une réponse JSON unique.
`image_config`	objet	non	Options de génération d'image, prises en compte uniquement avec un modèle image compatible.

Les réglages de génération (instructions, température, raisonnement, outils et limites de tokens) sont définis par le modèle prédéfini choisi. Les paramètres OpenAI homonymes ne sont donc pas exposés directement par cet endpoint.

Options `image_config`

image_config est transmis au fournisseur pour les presets de génération d'image, tels que gpt-image, nano-banana, flux-2 ou recraft-fast. Il est ignoré avec les modèles de conversation. La disponibilité exacte des valeurs dépend du modèle choisi.

Champ	Valeurs / format	Valeur par défaut
`action`	`generate`, `edit`, `auto`	`auto`
`background`	`transparent`, `opaque`, `auto`	selon le modèle
`image_count`	entier	`1`
`output_compression`	entier de `0` à `100`	selon le modèle
`size`	par exemple `1024x1024`, `1024x1536`, `1536x1024` ou `auto`	`1024x1024`
`aspect_ratio`	par exemple `1:1`, `4:3`, `3:4`, `16:9`, `9:16` ou `auto`	selon le modèle
`resolution`	`512`, `1K`, `2K`, `4K`	selon le modèle
`quality`	`auto`, `low`, `medium`, `high`	`auto`
`output_format`	`png`, `jpeg`, `webp`, `svg`	selon le modèle
`response_format`	`BASE64`, `URL`	selon le modèle

Par exemple, pour générer une image carrée avec un fond transparent :

json

{
  "thread_id": "thd-xxx",
  "model": "gpt-image",
  "stream": false,
  "image_config": {
    "action": "generate",
    "background": "transparent",
    "size": "1024x1024",
    "aspect_ratio": "1:1",
    "quality": "high",
    "output_format": "png"
  },
  "messages": [
    {
      "type": "message",
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Un logo minimaliste de renard bleu" }
      ]
    }
  ]
}

Gestion des conversations

Lister les threads

Utilisez GET /api/threads pour lister les threads de l'utilisateur authentifié. La réponse est paginée et les threads sont dans le champ data.

bash

curl --request GET "https://haloon.ai/api/threads?limit=30&offset=0&sort_by=created_at&order_by=desc" \
  --header "Authorization: Bearer $HALOON_API_KEY"

Paramètre	Valeur par défaut	Description
`sort_by`	`created_at`	Champ utilisé pour le tri.
`order_by`	`desc`	Ordre de tri : `asc` ou `desc`.
`global_search`	—	Terme de recherche global.
`offset`	`0`	Nombre d'éléments à ignorer.
`limit`	`30`	Nombre maximal d'éléments retournés.

Si vous avez transmis une chaîne quelconque lors de la création, faite une recherche par created_at desc et retrouvez le thread en première position avec son id au format thd-<uuid>.

Lister les messages d'un thread

Utilisez GET /api/threads/:thread_id/messages pour récupérer les messages d'une conversation. La pagination fonctionne de la même façon.

bash

curl --request GET "https://haloon.ai/api/threads/$THREAD_ID/messages" \
  --header "Authorization: Bearer $HALOON_API_KEY"

API ​

Sécurité ​

Créer une conversation avec un LLM ​

Créer un thread_id ​

Envoyer le premier message ​

Répondre dans la même conversation ​

Paramètres ​

Options image_config ​

Gestion des conversations ​

Lister les threads ​

Lister les messages d'un thread ​

API

Sécurité

Créer une conversation avec un LLM

Créer un `thread_id`

Envoyer le premier message

Répondre dans la même conversation

Paramètres

Options `image_config`

Gestion des conversations

Lister les threads

Lister les messages d'un thread