Guide d’intégration
Les modèles de texte parlent ici les protocoles que votre SDK parle déjà : Chat Completions, le sous-ensemble sans état de Responses, Anthropic Messages et Google generateContent. La question intéressante concerne les paramètres que le modèle cible n’a jamais déclarés.
L’enjeu
L’échec classique n’est pas un 500. C’est un paramètre que votre passerelle a accepté, jeté et jamais mentionné : le modèle a tourné sans votre temperature, vos définitions d’outils ou votre format de réponse, et la sortie a simplement paru décevante plutôt que cassée.
01
messages, tools, tool_choice, response_format, max_tokens, temperature et top_p correspondent aux champs déclarés du modèle. Le reste est transmis au schéma du modèle et renvoie 400 s’il ne le déclare pas. Le silence n’est jamais la réponse.
02
Sur /v1 le corps est un objet d’erreur OpenAI ou Anthropic, pas l’enveloppe {code, msg, data, request_id} de /api/v1. Si vous mélangez les deux surfaces, traitez les deux formes.
03
stream: true renvoie des événements chat.completion.chunk terminés par data: [DONE]. La facturation suit toujours l’usage mesuré : un flux interrompu n’est pas une requête gratuite.
La méthode
Modifiez base_url et api_key, remplacez la chaîne de modèle par une valeur de GET /v1/models et lancez la suite de tests que vous avez déjà. Un 400 sur un paramètre signifie que le modèle choisi ne l’a jamais pris en charge — une information que la version silencieuse ne donnait pas.
N’importe quel client compatible OpenAI convient. Seules l’URL de base et la valeur model changent.
POST /v1/chat/completions
from openai import OpenAI
client = OpenAI(
base_url="https://api.spicyapi.ai/v1",
api_key=os.environ["SPICY_API_KEY"],
)
stream = client.chat.completions.create(
model="<publisher>/<model>/chat", # exact value from GET /v1/models
messages=[{"role": "user", "content": "Summarise these notes in three bullets."}],
temperature=0.7,
stream=True,
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="")text/event-stream
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"- "}}]}
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"Ships"}}]}
data: [DONE]Contrat
| Champ ou en-tête | Valeur ou limite |
|---|---|
| POST /v1/chat/completions | chat.completion · SSE with stream: true |
| GET /v1/models | every callable model value |
| Authorization: Bearer · x-api-key · x-goog-api-key | accepted on /v1 |
| undeclared parameter | 400 · never silently dropped |
Balayez horizontalement pour voir toutes les colonnes.
Intégration
Pertinence
Vérifications
/v1/chat/completions, /v1/responses, /v1/messages et /v1beta/models/{model}:generateContent s’authentifient toutes avec la même clé. Authorization: Bearer, x-api-key et x-goog-api-key sont acceptés là où le SDK les attend.
GET /v1/models renvoie exactement les identifiants acceptés par toutes les opérations /v1 et /api/v1, avec l’éditeur dans owned_by. Les prix viennent de /api/v1/models, spécifique au compte et donc privé.
La couche de compatibilité réutilise la même authentification, les mêmes limites de débit, la même validation, la même tarification et la même réservation que la surface native. Seule l’enveloppe diffère.
Avant la mise en production
Questions fréquentes
Modèles
Chaque lien ouvre la page de la famille de modèles concernée : entrées, limites, politique de contenu et prix actuel à l’unité.
Et après
Pointez un client OpenAI, Anthropic ou Google existant vers SpicyAPI. Ce qui passe tel quel, ce qui est refusé exprès, et comment le texte est facturé.
