API Chat v3 : d’une requête simple au streaming et à la vision

Informations de base

Authentification

Clé API

Le point de terminaison nécessite une clé API avec l’autorisation (portée) ayeto.chat.

En-tête d’authentification

uni-api-key: <VOTRE_CLÉ_API>

Format de la clé API

La clé API a le format suivant :

ayeto-{64_caractères_hexadécimaux_aléatoires}

Exemple :

ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Portées

Pour utiliser le point de terminaison de chat, la clé API doit avoir l’une des portées suivantes : - ayeto.chat - portée spécifique au chat - * - portée générique (accès à tous les points de terminaison)

Réponses d’erreur d’authentification

Sécurité : Lorsqu’une clé API invalide est utilisée, un délai de sécurité est appliqué pour protéger contre les attaques par force brute.

Corps de la requête - ChatRequest

Important : assistant_id OU model doit être fourni. L’un de ces champs est obligatoire.

Pièces jointes - EncodedData

Pour joindre des documents ou des images, utilisez le champ documents :

Limitation : Une seule image avec vision: true est autorisée dans une requête unique.

Réponse - BasicLLMMessageView

Exemple de réponse

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1735815581000,
  "role": "assistant",
  "content": "Bonjour ! Je vais bien, merci de demander. Comment puis-je vous aider ?",
  "reasoning_content": null,
  "model": "gpt-4o",
  "img_gen": null
}

Réponse de génération d’image - ImgGenMessage

Si image: true, la réponse contient un objet img_gen :

Réponse en streaming (SSE)

Si stream: true, le point de terminaison renvoie un flux Server-Sent Events (SSE).

En-têtes de réponse du streaming

Content-Type: text/event-stream
Transfer-Encoding: chunked

Format des segments du flux - StreamChunk

Chaque segment est un objet JSON sur une ligne séparée :

Format d’erreur du flux - StreamError

Si une erreur se produit pendant le streaming :

Exemple de réponse en streaming

{"timestamp": 1735815581000, "data": "Bonjour", "error": null}
{"timestamp": 1735815581050, "data": ",", "error": null}
{"timestamp": 1735815582100, "data": " comment", "error": null}
{"timestamp": 1735815582150, "data": " allez", "error": null}
{"timestamp": 1735815582200, "data": " vous", "error": null}
{"timestamp": 1735815583000, "data": " ?", "error": null}

Exemple d’erreur en streaming

{"timestamp": 1735815590000, "data": null, "error": {"status": 500, "text": "Internal Server Error", "detail": "Model timeout"}}

Exemples cURL

1. Chat de base avec un modèle

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "message": "Bonjour, comment allez-vous ?"
  }'

2. Chat avec une conversation existante

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "model": "gpt-4o",
    "message": "Continuez le sujet précédent."
  }'

3. Chat avec un assistant

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "123e4567-e89b-12d3-a456-426614174000",
    "message": "Aidez-moi avec l’analyse de données."
  }'

4. Chat avec une pièce jointe (document)

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "message": "Analysez ce document.",
    "documents": [
      {
        "filename": "report.txt",
        "data": "data:text/plain;base64,VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
        "size": 25,
        "mime_type": "text/plain",
        "vision": false
      }
    ]
  }'

5. Chat avec une image (Vision)

# Encodez d’abord l’image en base64
IMAGE_BASE64=$(base64 -w 0 photo.jpg)  # Linux
# ou : IMAGE_BASE64=$(base64 -i photo.jpg)  # macOS

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"gpt-4o\",
    \"message\": \"Que voyez-vous dans cette image ?\",
    \"documents\": [
      {
        \"filename\": \"photo.jpg\",
        \"data\": \"data:image/jpeg;base64,${IMAGE_BASE64}\",
        \"size\": $(stat -f%z photo.jpg 2>/dev/null || stat -c%s photo.jpg),
        \"mime_type\": \"image/jpeg\",
        \"vision\": true
      }
    ]
  }"

6. Génération d’image

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "message": "Dessinez un coucher de soleil sur des montagnes dans le style de l’impressionnisme.",
    "image": true
  }'

7. Réponse en streaming

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "gpt-4o",
    "message": "Écrivez une courte histoire sur un robot.",
    "stream": true
  }'

Astuce : L’option -N (ou --no-buffer) désactive la mise en mémoire tampon pour l’affichage du flux en temps réel.

8. Streaming avec traitement des segments (Bash + jq)

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -N -s \
  -d '{
    "model": "gpt-4o",
    "message": "Expliquez la physique quantique.",
    "stream": true
  }' | while IFS= read -r line; do
    echo "$line" | jq -r '.data // empty' | tr -d '\n'
  done
echo ""

9. Chat dans le contexte d’une organisation

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "550e8400-e29b-41d4-a716-446655440000",
    "model": "gpt-4o",
    "message": "Quels sont nos objectifs d’entreprise ?"
  }'

10. Chat avec limite de jetons

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "message": "Résumez l’histoire des ordinateurs.",
    "max_tokens": 500
  }'

11. Chat avec outils dynamiques et historique pertinent

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "123e4567-e89b-12d3-a456-426614174000",
    "message": "Trouvez les informations météo à Prague.",
    "relevant_history": true,
    "dynamic_tools": true
  }'

12. Chat avec appels d’outils supprimés de la réponse

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "123e4567-e89b-12d3-a456-426614174000",
    "message": "Calculez 2+2 à l’aide d’une calculatrice.",
    "remove_tool_calls": true
  }'

13. Exemple complet avec plusieurs paramètres

curl -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "assistant_id": "abcd1234-e89b-12d3-a456-426614174000",
    "message": "Analysez le document joint et créez un résumé.",
    "max_tokens": 1000,
    "relevant_history": true,
    "dynamic_tools": true,
    "stream": false,
    "remove_tool_calls": true,
    "documents": [
      {
        "filename": "report.pdf",
        "data": "data:application/pdf;base64,JVBERi0xLjQK...",
        "size": 102400,
        "mime_type": "application/pdf",
        "vision": false
      }
    ]
  }'

14. cURL détaillé pour le débogage

curl -v -X POST "https://beta.ayeto.ai/api/v3/chat" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "message": "Message de test"
  }'

États d’erreur

Exemple de réponse d’erreur

{
  "detail": "API key is invalid"
}

Règles de validation

1. Modèle vs Assistant : assistant_id OU model doit être fourni (pas les deux vides).
2. Limite de vision : Maximum d’un document avec vision: true par requête.
3. Jetons max : Si fourni, il doit respecter les limites du modèle.
4. Conversation : Si une conversation avec l’ID donné existe, elle doit appartenir à l’utilisateur actuel.
5. Portée de la clé API : La clé API doit avoir la portée ayeto.chat ou *.