Resumen

Endpoints

Todos los endpoints viven bajo una única URL base y se sirven por HTTPS.

https://api.shannon-ai.com

Los tres endpoints que producen texto llegan a los mismos modelos. Elige aquel cuyo formato ya usa tu código.

Conceptos básicos de las solicitudes

• El cuerpo de cada POST es un objeto JSON, de hasta 32 MiB.
• Un campo que la API no conoce no causa ningún error y no tiene efecto. Una solicitud escrita para otro proveedor no falla por un campo adicional.
• Un campo conocido con un tipo JSON incorrecto, o un campo obligatorio que falta, se responde con 422. Un cuerpo que no es JSON válido se responde con 400.
• model es uno de los ids de Modelos y precios. No importan las mayúsculas ni las minúsculas.

Una respuesta es JSON, o un stream de server-sent events cuando la solicitud establece stream en true. Cada endpoint responde en su propio formato. Toda respuesta tiene el header x-request-id.

Qué comprobaciones pasa una solicitud

Una solicitud se comprueba en un orden fijo antes de que se ejecute un modelo. Responde la primera comprobación que falla, así que un 401 aún no te dice nada sobre el cuerpo.

Forma de los errores

Un error es un objeto JSON con un error que contiene type y message. /v1/messages lo envuelve como esperan los SDK de Anthropic; todas las demás rutas usan la forma de OpenAI.

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

• Lee type y message. code y param están presentes solo en algunos errores: trátalos como opcionales. param es siempre null.
• Una vez iniciado un stream, el estado ya es 200. Un fallo llega entonces como una trama de error dentro del stream.
• Toda respuesta de error lleva el header x-request-id.

Manejo de errores

Facturación y saldo

• Hay un saldo por cuenta, y el chat y la API lo comparten: primero la cuota del plan de hoy y después el crédito comprado. La API no tiene una cuota propia.
• Una solicitud reserva su presupuesto de salida (max_tokens, 4,096 por defecto) y luego se cobra por los tokens que realmente usó, al precio del modelo.
• Cada respuesta informa de sus recuentos de tokens en usage. La página Claves y uso muestra el saldo y lo que costó cada solicitud.
• Todas las solicitudes se atienden por igual. El único límite de tasa de solicitudes es la protección contra flood: 120 solicitudes por minuto por cuenta. Las solicitudes enviadas en paralelo esperan en cola.

Límites y saldo Modelos y precios Claves y uso

Campos que dependen del modelo

Todos los modelos aceptan la misma solicitud. Algunos campos surten efecto solo en ciertos modelos; la tabla indica dónde. Las páginas de cada endpoint listan todos los campos.

Chat Completions

Si vienes de un SDK de OpenAI

• Establece la URL base en https://api.shannon-ai.com/v1 y la clave en tu clave de Shannon. Las llamadas a Chat Completions y Responses funcionan entonces con el SDK tal como está.
• model debe ser un id de Shannon. Un nombre de modelo de otro proveedor, como gpt-4o, se responde con 400 y unknown model.
• El razonamiento llega en un campo propio: reasoning_content junto a content, en el mensaje y en los deltas del stream.
• Un stream siempre lleva usage en su último fragmento, junto con finish_reason.
• Una llamada a herramienta en un stream llega como un solo fragmento con la cadena arguments completa.
• Una respuesta tiene una choice.
• Las rutas de la API de OpenAI que no están en la tabla anterior, como /v1/embeddings, se responden con 404.

Si vienes de un SDK de Anthropic

• Establece la URL base en https://api.shannon-ai.com, sin /v1, y la clave en tu clave de Shannon. El SDK la envía como x-api-key.
• model debe ser un id de Shannon.
• max_tokens es opcional en esta API. Su valor predeterminado es 4,096.
• Una respuesta contiene bloques de contenido de tipo thinking, text y tool_use. El primer bloque no siempre es el texto: elige los bloques por type.
• stop_reason es end_turn o tool_use. Un stream de un modelo Shannon también puede terminar con max_tokens.
• Se aceptan anthropic-version y anthropic-beta, de modo que el SDK funciona sin cambios. Una solicitud no los necesita.
• Los errores en /v1/messages tienen la forma de Anthropic: {"type": "error", "error": {…}}.

Las herramientas de programación que hablan estos formatos se configuran igual: URL base, clave y un id de Shannon como modelo. Herramientas CLI de programación