Texto

Crear Chat Completion

Crea una completion para el mensaje de chat

POST
/v1/chat/completions

Cuerpo de la solicitud

Los parámetros opcionales admitidos, los valores aceptados y los valores predeterminados dependen del modelo seleccionado. Consulta los detalles del modelo antes de configurar las opciones de muestreo, razonamiento o herramientas. Un control que el modelo no pueda cumplir, como n superior a 1 en algunos modelos, se rechaza con un error 4xx. En su lugar, los controles de muestreo menores como seed o las penalizaciones pueden ser ignorados.

modelstringobligatorio

ID del modelo a utilizar. Consulta Modelos para conocer las opciones disponibles.

messagesarrayobligatorio

Una lista de mensajes que componen la conversación.

Cada objeto de mensaje contiene:

  • role (string): system, developer, user, assistant, tool, function
  • content (string | array | null): El contenido del mensaje

Para un mensaje de assistant que contenga tool_calls, content puede omitirse o establecerse en null.

Cuando content es un array, TokenLab admite bloques multimodales estructurados para modelos compatibles:

  • texto: { "type": "text", "text": "..." }
  • imagen: { "type": "image_url", "image_url": { "url": "https://..." } }
  • video: { "type": "video_url", "video_url": { "url": "https://..." } }
  • audio: { "type": "input_audio", "input_audio": { "data": "https://... or base64 data URL", "format": "wav" } }, o { "type": "audio_url", "audio_url": { "url": "https://..." } }

Para la entrada multimodal, utiliza URLs https accesibles públicamente. Las imágenes también se pueden enviar como data URLs en base64. Los tipos de medios admitidos dependen del modelo seleccionado.

temperaturenumber

Temperatura de muestreo. La compatibilidad, los valores permitidos y el valor predeterminado dependen del modelo seleccionado; omite este campo para usar su valor predeterminado.

max_tokensinteger

Número máximo de tokens a generar. Envía max_tokens o max_completion_tokens, no ambos: un modelo servido a través de otro protocolo puede rechazar una solicitud que contenga ambos.

En un modelo que piensa, los tokens de pensamiento cuentan para este límite. Si el límite es demasiado pequeño, todo el presupuesto puede destinarse al pensamiento y dejar el cuerpo del mensaje vacío, y los tokens utilizados se seguirán facturando. Aumenta el límite o desactiva el pensamiento donde el modelo lo permita, por ejemplo con "reasoning_effort": "none". En deepseek-v4.1-flash (alias deepseek-flash), "thinking": {"type": "disabled"} también lo desactiva.

Antes de ejecutar la solicitud, TokenLab verifica que tu saldo cubra este máximo. Un valor muy grande puede devolver 402 con un saldo bajo, incluso cuando la respuesta sea corta.

streambooleanpredeterminado: false

Si es true, las diferencias parciales del mensaje se envían como server-sent events (SSE). Consulta Streaming.

Para respuestas largas (miles de tokens o más), establece stream: true para que los clientes y proxies no agoten el tiempo de espera mientras aguardan la respuesta completa.

stream_optionsobject

Opciones para streaming. Establece include_usage: true para recibir un chunk adicional con el uso de tokens antes de data: [DONE]. Sin él, el stream no incluye información de uso.

top_pnumber

Parámetro de muestreo por núcleo (nucleus sampling). Recomendamos modificar este parámetro o la temperatura, no ambos.

frequency_penaltynumber

Número entre -2.0 y 2.0. Los valores positivos penalizan los tokens repetidos.

presence_penaltynumber

Número entre -2.0 y 2.0. Los valores positivos penalizan los tokens que ya están presentes en el texto.

stopstring | array

Secuencia o lista de secuencias de parada. La compatibilidad y los límites de secuencias dependen del modelo seleccionado.

toolsarray

Una lista de herramientas que el modelo puede llamar (function calling). Cada herramienta es { "type": "function", "function": { "name": "...", "description": "...", "parameters": { ... } } }. Consulta Salidas estructuradas y llamada a herramientas.

tool_choicestring | object

Controla cómo el modelo utiliza las herramientas. Opciones: auto, none, required o { "type": "function", "function": { "name": "..." } } para forzar una herramienta.

parallel_tool_callsboolean

Permite múltiples llamadas a herramientas en un solo turno del asistente, cuando el modelo seleccionado lo admita.

max_completion_tokensinteger

Límite superior para la completion, incluidos los tokens de pensamiento. Alternativa a max_tokens utilizada por las familias de modelos de OpenAI más recientes. Envía solo uno de los dos.

reasoning_effortstring

Esfuerzo de razonamiento para los modelos que lo admiten. Los valores aceptados dependen del modelo seleccionado.

Para los modelos Claude, el valor establece el pensamiento del modelo: un nivel de esfuerzo en modelos con pensamiento adaptativo, o un presupuesto de pensamiento en modelos que utilizan uno. none desactiva el pensamiento en los modelos que lo permiten. Un valor que el modelo no admita se rechaza con 400, código invalid_value, y el error enumera los valores admitidos. Mientras el pensamiento está activo, Claude rechaza una temperature distinta de 1, top_k, un top_p fuera de 0.95–1 y un mensaje de asistente precompletado. Un tool_choice forzado funciona con el pensamiento adaptativo, pero no con un presupuesto de pensamiento.

anthropic_optionsobject

Opciones para los modelos Claude.

  • prompt_caching (boolean): Establece true para almacenar en caché el inicio del prompt. TokenLab marca el final del prompt del sistema y el último mensaje del usuario como puntos de caché. Una solicitud posterior que comience con el mismo contenido lo leerá de la caché. Utiliza esta opción o tus propias marcas de cache_control, no ambas.
  • prompt_caching_ttl (string): 5m (predeterminado) o 1h. Cuando el servicio que gestiona la solicitud no puede mantener una caché durante una hora, TokenLab puede utilizar la caché de cinco minutos en lugar de rechazar la solicitud.

extra.prompt_caching y extra.prompt_caching_ttl se aceptan como las mismas opciones. Consulta Caché de prompts para conocer los precios y cómo verificar los tokens almacenados en caché.

seedinteger

Semilla de muestreo para los modelos que lo admiten. No se garantiza una salida idéntica.

ninteger

Número de completions a generar. Los modelos que lo admiten aceptan entre 1 y 128. Muchos modelos solo admiten 1.

logprobsboolean

Indica si se deben devolver probabilidades logarítmicas.

top_logprobsinteger

Número de probabilidades logarítmicas principales a devolver (0-20). Requiere logprobs: true.

top_kinteger

Muestreo Top-K para los modelos que lo admiten.

response_formatobject

Formato de respuesta. Usa {"type": "text"} (predeterminado), {"type": "json_object"} para el modo JSON, o {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}} para un esquema JSON. La compatibilidad depende del modelo seleccionado. Consulta Salidas estructuradas y llamada a herramientas.

logit_biasobject

Modifica la probabilidad de que aparezcan tokens específicos. Asigna IDs de tokens (como cadenas) a valores de sesgo de -100 a 100. La compatibilidad depende del modelo seleccionado.

service_tierstring

TokenLab atiende y factura las solicitudes de Chat en el nivel de servicio estándar. Se aceptan auto y default. Otros valores, como flex o priority, se eliminan de la solicitud y esta se factura al precio estándar.

userstring

Un identificador único que representa a tu usuario final para la supervisión de abusos.

Respuesta

idstring

Identificador único para la completion.

objectstring

Siempre chat.completion.

createdinteger

Marca de tiempo Unix de cuándo se creó la completion.

modelstring

El modelo utilizado para la completion.

choicesarray

Lista de opciones de completion.

Cada opción contiene:

  • index (integer): Índice de la opción
  • message (object): El mensaje generado
  • finish_reason (string): Por qué se detuvo el modelo, por ejemplo stop, length, tool_calls o content_filter

Cuando el modelo piensa, message también puede contener:

  • reasoning_content (string): El texto de pensamiento. Algunos modelos solo devuelven un resumen o ningún texto.
  • reasoning_details (array): Bloques de pensamiento con sus firmas. Para continuar una conversación con pensamiento, por ejemplo después de una llamada a una herramienta, envíalos de vuelta sin modificar en el mensaje del asistente.

En un stream, los mismos campos llegan como delta.reasoning_content y delta.reasoning_details.

usageobject

Estadísticas de uso de tokens.

  • prompt_tokens (integer): Tokens en el prompt
  • completion_tokens (integer): Tokens en la completion, incluidos los tokens de pensamiento
  • total_tokens (integer): Total de tokens utilizados
  • prompt_tokens_details.cached_tokens (integer): Tokens de prompt leídos de la caché
  • cache_creation_input_tokens (integer): Tokens de prompt escritos en la caché. Presente solo cuando el valor sea mayor que 0
  • completion_tokens_details.reasoning_tokens (integer): Tokens de pensamiento, cuando el modelo los reporte

En un stream, el uso solo llega cuando stream_options.include_usage es true.

Solicitud

curl -X POST "https://api.tokenlab.sh/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 1000
  }'

Ejemplo multimodal

{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this video briefly." },
        { "type": "video_url", "video_url": { "url": "https://example.com/demo.mp4" } }
      ]
    }
  ],
  "max_tokens": 64
}

Respuesta

Response
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1706000000,
  "model": "gpt-5.6-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 9,
    "total_tokens": 29
  }
}

Streaming

Con stream: true, la respuesta es un text/event-stream. Cada evento es data: {...} con un objeto chat.completion.chunk cuyo choices[].delta transmite el nuevo texto, los argumentos de llamada a herramientas o el texto de pensamiento. El stream finaliza con data: [DONE]. Las líneas que comienzan con : son comentarios de keep-alive: ignóralas. Un stream que finalice sin [DONE] o sin un finish_reason está incompleto. Consulta Streaming.

Errores

Los errores utilizan el objeto error al estilo de OpenAI. Casos comunes: 400 para un campo no válido o un valor que el modelo no acepta, 401 para una clave no válida, 402 por saldo insuficiente, 413 para entradas que superan el límite de tamaño y 429 por límite de tasa de solicitudes (rate limit). Consulta Gestionar errores de la API.

Autorización

BearerAuth
AuthorizationBearer <token>

Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.

Ubicación: header

Encabezados

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitud. Sustituye los valores predeterminados de la API key y del Workspace. Auto intenta primero con TokenLab Verified y puede cambiar una vez a Official solo antes de la salida, la aceptación de la solicitud o la creación de recursos persistentes.

Valores permitidos

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Clave opcional que detiene una segunda ejecución de la misma solicitud. Envíe un nuevo valor único, como un UUID, para cada solicitud y consérvelo para reintentos después de un tiempo de espera. Un reintento con la misma clave no se ejecuta de nuevo: devuelve 409 con idempotency_replay_unavailable, o generalmente idempotency_conflict cuando el cuerpo ha cambiado. Excepción: cuando un resultado que no es de streaming finaliza después de que el cliente se desconectó, un reintento con la misma clave y cuerpo dentro de las 24 horas devuelve ese resultado (hasta 1 MB) con el encabezado Idempotent-Replayed: true y sin un segundo cargo. Se ignora una clave de más de 255 caracteres y la solicitud no tendrá protección de idempotencia. Consulte Reintente de forma segura con una clave de idempotencia.

Longitud1 <= length <= 255

Cuerpo de la solicitud

application/json

Respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json