Conventions

Base de format

Les endpoints de chat consomment et renvoient du JSON. En mode streaming, la reponse est diffusee en text/event-stream.

Champ model

Le champ model est obligatoire et doit suivre l’un de ces formats:

group:<uuid>
custom:<uuid>

Exemple:

group:123e4567-e89b-12d3-a456-426614174000
custom:123e4567-e89b-12d3-a456-426614174111

Les cibles group:<uuid> peuvent utiliser les modes auto, normal, orch ou synth. Les cibles custom:<uuid> fonctionnent toujours en mode normal. Si une cible custom recoit metadata.mode avec orch ou synth, l’API renvoie 400.

Messages

La requete attend un tableau messages.

Roles acceptes:

• system
• user
• assistant
• tool

Regle importante:

• le tableau doit contenir au moins un message user
• le dernier message user porte la demande en cours
• les messages tool sont acceptes pour compatibilite mais ne sont pas transmis comme historique de chat
• tool_call_id est optionnel et peut contenir jusqu’a 200 caracteres

Formats de contenu

Le champ content d’un message peut etre:

• une chaine
• null
• un tableau de blocs contenant des proprietes comme type et text

Streaming

Si stream vaut true, l’API renvoie des evenements SSE.

Le flux suit en pratique cette logique:

1. un premier chunk initialise la reponse assistant
2. des chunks ajoutent du texte dans choices[0].delta.content
3. un chunk final ferme la reponse
4. le flux se termine avec data: [DONE]

metadata

Le champ metadata est optionnel. Il est utile notamment pour:

• fournir un identifiant request_id
• indiquer un mode via metadata.mode

Valeurs de metadata.mode prises en charge:

• auto
• normal
• orch
• synth

Les champs inconnus de la requete sont ignores. Les champs pris en charge sont listes sur chaque page d’endpoint.

Effort de raisonnement

L’effort de raisonnement peut etre transmis de trois facons:

• reasoning_effort: s’applique a la cible brain
• reasoning.effort: forme objet compatible OpenAI, s’applique aussi a la cible brain
• reasoning_effort_overrides: objet qui associe des identifiants de cible comme brain ou agent:0 a un effort

Valeurs acceptees:

• none
• minimal
• low
• medium
• high
• xhigh
• max

Les valeurs explicites de reasoning_effort_overrides ont priorite sur reasoning_effort et reasoning.effort.

Identifiants de requete

Les clients peuvent envoyer x-request-id avec des lettres, chiffres, ., _, : ou -, jusqu’a 128 caracteres. L’API renvoie l’identifiant retenu dans le meme en-tete et dans les erreurs.

metadata.request_id peut aussi fournir un identifiant applicatif. Quand il est present et non vide, il est utilise dans les metadonnees d’execution Kitemesh.

Limites de saisie utiles

• messages: entre 1 et 500 elements
• temperature: entre 0 et 2
• max_tokens: entre 1 et 200000
• max_completion_tokens: entre 1 et 200000
• denied_tools[].reason: jusqu’a 2000 caracteres
• approved_tool_execution_ids et denied_tools: jusqu’a 200 elements chacun sur les requetes de reprise

Si max_tokens et max_completion_tokens sont fournis ensemble, preferez max_completion_tokens pour exprimer clairement la limite souhaitee.