Texto
Crear Chat Completion
Crea una completion para el mensaje de chat
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.
ID del modelo a utilizar. Consulta Modelos para conocer las opciones disponibles.
Una lista de mensajes que componen la conversación.
Cada objeto de mensaje contiene:
role(string):system,developer,user,assistant,tool,functioncontent(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.
Temperatura de muestreo. La compatibilidad, los valores permitidos y el valor predeterminado dependen del modelo seleccionado; omite este campo para usar su valor predeterminado.
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.
falseSi 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.
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.
Parámetro de muestreo por núcleo (nucleus sampling). Recomendamos modificar este parámetro o la temperatura, no ambos.
Número entre -2.0 y 2.0. Los valores positivos penalizan los tokens repetidos.
Número entre -2.0 y 2.0. Los valores positivos penalizan los tokens que ya están presentes en el texto.
Secuencia o lista de secuencias de parada. La compatibilidad y los límites de secuencias dependen del modelo seleccionado.
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.
Controla cómo el modelo utiliza las herramientas. Opciones: auto, none, required o { "type": "function", "function": { "name": "..." } } para forzar una herramienta.
Permite múltiples llamadas a herramientas en un solo turno del asistente, cuando el modelo seleccionado lo admita.
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.
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.
Opciones para los modelos Claude.
prompt_caching(boolean): Establecetruepara 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 decache_control, no ambas.prompt_caching_ttl(string):5m(predeterminado) o1h. 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é.
Semilla de muestreo para los modelos que lo admiten. No se garantiza una salida idéntica.
Número de completions a generar. Los modelos que lo admiten aceptan entre 1 y 128. Muchos modelos solo admiten 1.
Indica si se deben devolver probabilidades logarítmicas.
Número de probabilidades logarítmicas principales a devolver (0-20). Requiere logprobs: true.
Muestreo Top-K para los modelos que lo admiten.
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.
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.
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.
Un identificador único que representa a tu usuario final para la supervisión de abusos.
Respuesta
Identificador único para la completion.
Siempre chat.completion.
Marca de tiempo Unix de cuándo se creó la completion.
El modelo utilizado para la completion.
Lista de opciones de completion.
Cada opción contiene:
index(integer): Índice de la opciónmessage(object): El mensaje generadofinish_reason(string): Por qué se detuvo el modelo, por ejemplostop,length,tool_callsocontent_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.
Estadísticas de uso de tokens.
prompt_tokens(integer): Tokens en el promptcompletion_tokens(integer): Tokens en la completion, incluidos los tokens de pensamientototal_tokens(integer): Total de tokens utilizadosprompt_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 0completion_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
{
"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 Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.
Ubicación: header
Encabezados
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"
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.
1 <= length <= 255Cuerpo de la solicitud
application/json
Respuesta
application/json
application/json
application/json
application/json
application/json
application/json
application/json