Saltar al contenido principal
Las salidas estructuradas y las llamadas a herramientas son contratos específicos de ruta. TokenLab reenvía varios formatos de API públicos, por lo que el patrón de producción más seguro es mantener cada forma nativa de herramienta del proveedor en la ruta que la posee y validar la salida del modelo en tu propia aplicación.

​
Elegir La Ruta

NecesidadRutaUsa esta forma
Respuestas de objeto JSON portátiles/v1/chat/completionsresponse_format: {"type": "json_object"}
Llamadas a funciones compatibles con OpenAI/v1/chat/completionstools: [{ "type": "function", "function": ... }]
Herramientas de Respuestas de OpenAI/v1/responsesCampos de respuestas tools, tool_choice y text
Uso de herramientas nativas de Claude o pensamiento/v1/messagesEsquema de herramienta de Mensajes de Anthropic
Declaraciones de funciones de Gemini o herramientas integradas/v1beta/models/:model:generateContenttools nativos de Gemini y partes de contenido
No envíes herramientas integradas nativas del proveedor a través de una ruta diferente y esperes que TokenLab las traduzca silenciosamente.

​
Modo JSON

Para respuestas estructuradas portátiles, comienza con el modo JSON de Chat Completions: 
{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "Devuelve un objeto JSON con ciudad y clima."
    }
  ],
  "response_format": { "type": "json_object" }
}
La validación compartida estable para Chat Completions acepta text y json_object. Puede existir json_schema, strict y aplicación de esquemas específicos del proveedor para algunas rutas o caminos de conversión, pero no son una promesa generalizada en cada ruta y modelo de TokenLab. Verifícalos contra el modelo seleccionado antes de confiar en ellos. Siempre analiza y valida el JSON devuelto en tu servidor. El modo JSON mejora la forma, pero no reemplaza la validación de esquema a nivel de aplicación.

​
Bucle de Llamadas a Herramientas

TokenLab no ejecuta tus funciones. Tu aplicación posee el bucle:
  1. Envía mensajes más definiciones de herramientas.
  2. Lee la respuesta del modelo para tool_calls, function_call, tool_use de Anthropic o partes de llamada a función de Gemini.
  3. Ejecuta la herramienta en tu propio backend.
  4. Agrega el resultado de la herramienta en el formato requerido por la misma ruta.
  5. Continúa la conversación hasta que el modelo devuelva una respuesta final.
Mantén la misma ruta a lo largo de un bucle de herramientas. Mezclar Chat Completions, Responses, Messages y formatos de Gemini en una conversación generalmente crea errores sutiles de estado y esquema.

​
Ejemplo de Chat Completions

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": "Extrae nombre y correo electrónico como JSON. Si es necesario, busca al cliente."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Busca un cliente por correo electrónico",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'

​
Diseño de Esquema

  • Mantén los esquemas pequeños y explícitos. Los esquemas anidados grandes añaden tokens y reducen la fiabilidad.
  • Prefiere campos requeridos para valores sin los cuales tu producto no puede continuar.
  • Usa enums para conjuntos cerrados de los que tu UI o backend dependen.
  • Incluye ejemplos en el prompt cuando el modelo tiene dificultades con una forma.
  • Trata los errores de campo no soportado como retroalimentación del contrato. Elimina el campo o utiliza la ruta nativa que lo documenta.

​
Lista de Verificación de Producción

  • Registra la ruta, modelo, nombres de herramientas y forma de esquema saneada en los logs.
  • Valida los argumentos de la herramienta antes de ejecutar cualquier efecto secundario.
  • Aplica tus propias verificaciones de permisos antes de la ejecución de la herramienta.
  • Haz que la ejecución de la herramienta sea idempotente cuando un reintento del cliente pueda repetir la misma llamada a la herramienta.
  • No registres secretos devueltos por herramientas en mensajes visibles para el modelo.

​
Referencia de API

TemaReferencia
API de Múltiples FormatosAPI de Múltiples Formatos
Crear Chat CompletionCrear Chat Completion
Crear RespuestaCrear Respuesta
Crear MensajeCrear Mensaje
Generar Contenido de GeminiGenerar Contenido de Gemini