API Chat

Utilisez POST /api/v1/chat/completions pour obtenir une réponse de chat complète sans streaming, ou POST /api/v1/chat/completions/stream pour les Server-Sent Events.

L'API Chat est basée sur les sessions. Omettez session_id pour démarrer une nouvelle session de chat API. Transmettez un session_id renvoyé pour continuer cette même session créée par l'API.

Portée actuelle

Chat API v1 prend en charge :

• les réponses d'assistant sans streaming
• le streaming SSE avec text/event-stream
• les sessions de chat créées par l'API
• la réservation de crédits du compte et le règlement final basé sur les tokens
• la recherche web, l'effort de raisonnement et le mode de pensée optionnels quand le modèle sélectionné les prend en charge
• les pièces jointes image via les valeurs file_id de l'API Files

Chat API v1 ne prend pas en charge :

• l'historique brut messages fourni par l'utilisateur
• la continuation des sessions réservées au Studio
• les URL de pièces jointes externes arbitraires
• les événements webhook du Chat

Scopes requis

Utilisez une clé API avec :

chat:create
chat:read

Les nouvelles clés créées dans les paramètres incluent les deux scopes par défaut. Les anciennes clés peuvent devoir être recréées avant d'appeler l'API Chat.

Créer une completion de chat

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Rédige un plan de lancement concis pour une nouvelle campagne visuelle produit",
    "client_request_id": "chat-001"
  }'

Réponse :

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "session_id": "session_id",
  "model": "gpt-5-2-chat",
  "created_at": "2026-05-11T00:00:00.000Z",
  "message": {
    "id": "assistant_message_id",
    "role": "assistant",
    "content": "..."
  },
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 320,
    "total_tokens": 1520
  },
  "credits": {
    "reserved": 3,
    "final": 2
  }
}

Streamer une completion de chat

Utilisez POST /api/v1/chat/completions/stream lorsque votre serveur veut recevoir les deltas de l'assistant à mesure qu'ils arrivent :

curl -N https://rivya.ai/api/v1/chat/completions/stream \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Idempotency-Key: chat-stream-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Rédige un plan de lancement concis pour une nouvelle campagne visuelle produit",
    "client_request_id": "chat-stream-001"
  }'

Les réponses en streaming utilisent Content-Type: text/event-stream; charset=utf-8.

Événements :

Exemple de stream :

event: session.created
data: {"request_id":"req_...","session_id":"session_id","model":"gpt-5-2-chat"}

event: message.delta
data: {"request_id":"req_...","session_id":"session_id","delta":"Draft ","index":0}

event: message.completed
data: {"request_id":"req_...","session_id":"session_id","message":{"id":"assistant_message_id","role":"assistant","content":"Draft ...","created_at":"2026-05-11T00:00:00.000Z"}}

event: usage.completed
data: {"request_id":"req_...","session_id":"session_id","usage":{"input_tokens":1200,"output_tokens":320,"total_tokens":1520},"credits":{"reserved":3,"final":2}}

event: done
data: {"request_id":"req_...","ok":true}

Si une erreur survient après le premier événement SSE, le stream envoie event: error, puis se ferme :

event: error
data: {"error":{"code":"internal_error","message":"The request could not be completed.","requestId":"req_..."}}

Si le client se déconnecte avant la fin, Rivya arrête le stream de génération en cours quand c'est possible. Les deltas partiels ne sont pas enregistrés comme message final de l'assistant. Si le serveur a déjà validé message.completed, le résultat final peut être relu plus tard avec GET /api/v1/chat/sessions/{sessionId}.

Continuer une session

Utilisez le session_id renvoyé :

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-002" \
  -d '{
    "model": "gpt-5-2-chat",
    "session_id": "session_id",
    "message": "Transforme maintenant cela en checklist opérationnelle en 5 étapes."
  }'

La session doit appartenir au même compte Rivya et avoir été créée par l'API publique. Les sessions réservées au Studio ne sont ni renvoyées ni continuées par l'API Chat.

Pièces jointes image

Les pièces jointes de chat utilisent des enregistrements de l'API Files, pas des URL externes.

1. Importez une image avec POST /api/v1/files.
2. Utilisez l'id renvoyé comme attachments[].file_id.

{
  "model": "gpt-5-2-chat",
  "message": "Analyse cette photo produit et propose une direction éditoriale plus nette.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Le fichier doit appartenir au même compte, avoir kind: "image" et être disponible. Les modèles qui ne prennent pas en charge les pièces jointes image renvoient chat_attachment_not_supported.

Contrôles optionnels

{
  "model": "gpt-5-2-chat",
  "message": "Compare trois options de lancement.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

La prise en charge des contrôles varie selon le modèle. Lisez /api/v1/models et vérifiez chat_capabilities avant d'exposer des contrôles dans votre interface.

Lister les sessions

Utilisez GET /api/v1/chat/sessions avec une clé qui inclut chat:read.

curl https://rivya.ai/api/v1/chat/sessions \
  -H "Authorization: Bearer rvya_sk_..."

Cela renvoie uniquement les sessions créées par l'API :

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "gpt-5-2-chat",
      "tool_slug": null,
      "title": "Write a concise launch plan...",
      "controls": {
        "enable_web_search": false,
        "reasoning_effort": null,
        "thought_mode": null
      },
      "created_at": "2026-05-11T00:00:00.000Z",
      "updated_at": "2026-05-11T00:00:00.000Z",
      "last_message_at": "2026-05-11T00:00:00.000Z"
    }
  ]
}

Obtenir une session

Utilisez GET /api/v1/chat/sessions/{sessionId} pour lire une session créée par l'API et ses messages validés.

curl https://rivya.ai/api/v1/chat/sessions/session_id \
  -H "Authorization: Bearer rvya_sk_..."

La réponse inclut les messages utilisateur et assistant validés. Elle n'expose pas les champs internes du fournisseur.

Idempotence

Utilisez Idempotency-Key pour chaque requête de production POST /api/v1/chat/completions et POST /api/v1/chat/completions/stream.

Si une nouvelle tentative utilise la même clé et le même corps, Rivya peut renvoyer la réponse stockée sans créer un autre message ni consommer de nouveau des crédits. Si la même clé est réutilisée avec une entrée différente, l'API renvoie idempotency_conflict.

Pour les nouvelles tentatives en streaming, Rivya ne rejoue pas les deltas historiques de tokens. Une relecture terminée renvoie une séquence SSE minimale avec session.created, message.completed, usage.completed et done.

Erreurs courantes

Pages associées

• Modèles API
• API Files
• Crédits API
• Erreurs et limites API
• Contrat OpenAPI et schéma