Guía de integración
Los modelos de texto hablan aquí los protocolos que tu SDK ya habla: Chat Completions, el subconjunto sin estado de Responses, Anthropic Messages y Google generateContent. Lo interesante es qué ocurre con un parámetro que el modelo de destino nunca declaró.
El reto
El fallo clásico no es un 500. Es un parámetro que tu pasarela aceptó, descartó y nunca mencionó: el modelo corrió sin tu temperature, tus definiciones de herramientas o tu formato de respuesta, y la salida pareció simplemente decepcionante en lugar de rota.
01
messages, tools, tool_choice, response_format, max_tokens, temperature y top_p se asignan a los campos declarados del modelo. El resto se reenvía a su esquema y devuelve 400 si el modelo no lo declara. El silencio nunca es la respuesta.
02
En /v1 el cuerpo es un objeto de error de OpenAI o Anthropic, no el sobre {code, msg, data, request_id} de /api/v1. Si mezclas ambas superficies, maneja las dos formas.
03
stream: true devuelve eventos chat.completion.chunk terminados con data: [DONE]. El cobro sigue el uso medido, así que un flujo interrumpido no es una petición gratuita.
El enfoque
Cambia base_url y api_key, sustituye la cadena de modelo por un valor de GET /v1/models y ejecuta la batería de pruebas que ya tienes. Si un parámetro devuelve 400, el modelo elegido nunca lo admitió: información que la versión silenciosa jamás te daba.
Sirve cualquier cliente compatible con OpenAI. Solo cambian la URL base y el valor model.
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]Contrato
| Campo o cabecera | Valor o límite |
|---|---|
| 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 |
Desliza horizontalmente para ver todas las columnas.
Integración
Encaje
Comprobaciones
/v1/chat/completions, /v1/responses, /v1/messages y /v1beta/models/{model}:generateContent se autentican con la misma clave. Authorization: Bearer, x-api-key y x-goog-api-key se aceptan allí donde el SDK los espera.
GET /v1/models devuelve exactamente los identificadores que aceptan todas las operaciones /v1 y /api/v1, con el creador en owned_by. Los precios salen de /api/v1/models, específico de la cuenta y por tanto privado.
La capa de compatibilidad reutiliza la misma autenticación, los mismos límites de tasa, la misma validación, el mismo cálculo de precio y la misma reserva que la superficie nativa. Solo cambia el sobre.
Antes del lanzamiento
Preguntas frecuentes
Modelos
Cada enlace abre la página de esa familia de modelos: entradas, límites, política de contenido y el precio actual por unidad.
Siguiente paso
Apunta un cliente de OpenAI, Anthropic o Google a SpicyAPI. Qué pasa tal cual, qué se rechaza a propósito y cómo se cobra el texto.
