Cómo elegir un nivel de entrega de TokenLab: Auto, Verified u Official

Una solicitud puede fallar con un error 503 aunque el ID del modelo sea perfectamente válido, y la causa suele ser el nivel de entrega que has fijado. En nuestro pipeline, nos encontramos con esto cuando forzamos una opción en un modelo que no la ofrecía. Esta guía explica las tres opciones de nivel de entrega, el orden en que se aplican los ajustes y lo que significa cada uno para tu factura. Todos los datos a continuación provienen de la documentación de TokenLab y de la API de modelos en vivo, observados el 03-10-2026.

Puntos clave

• Un nivel de entrega tiene tres valores: auto, verified y official.
• Un encabezado de solicitud anula el ajuste de la API key, el cual a su vez anula el valor predeterminado del Workspace.
• Si la opción solicitada no tiene disponibilidad, obtendrás un 503 delivery_tier_unavailable. Cuando retryable sea false, no vuelvas a enviar la misma solicitud.
• Pagas una vez, por la opción que completó la solicitud.
• Consulta GET /v1/models/{model} antes de fijar un nivel. Es público y no requiere una key.

Las tres opciones de nivel de entrega

La referencia de la API (observada el 03-10-2026) define tres opciones:

• Auto utiliza TokenLab Verified cuando está disponible, y luego Official si es necesario. Pagas por la opción que completa tu solicitud.
• TokenLab Verified es la entrega verificada por TokenLab. Se aplican los precios de TokenLab.
• Official se basa en el precio público del creador del modelo. El precio que se muestra en TokenLab es lo que pagas.

Las solicitudes de generación aceptan el encabezado X-TokenLab-Delivery-Policy: auto | verified | official. Un valor de encabezado no válido devuelve un 400.

Qué ajuste se aplica primero

Hay tres lugares donde se puede establecer el nivel de entrega. El orden documentado es:

1. El encabezado de la solicitud.
2. El ajuste de la API key.
3. El valor predeterminado del Workspace.

El encabezado anula la key, y la key anula el Workspace. Las sesiones en tiempo real (Realtime sessions) son la excepción: utilizan el ajuste de la API key o del Workspace y no aceptan una anulación mediante cadena de consulta (query-string).

Establecer el nivel de entrega en una solicitud

Aquí tienes una llamada de Chat Completions que fija la entrega Official. El ID del modelo claude-sonnet-5 aparece en la API de modelos en vivo con ambas opciones disponibles. Consulta la página del modelo.

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-TokenLab-Delivery-Policy: official" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

El mismo encabezado funciona en el endpoint de Anthropic Messages. Para /v1/messages, el encabezado de la key puede ser x-api-key, que según la referencia de la API, Anthropic Messages acepta.

curl https://api.tokenlab.sh/v1/messages \
  -H "x-api-key: $TOKENLAB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -H "X-TokenLab-Delivery-Policy: verified" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Establecer el nivel de entrega en una API key

Para hacer que un nivel de entrega sea el predeterminado para una key, utiliza la API de gestión con un token de gestión (mt-...). Las páginas Create API Key y Update API Key (ambas observadas el 03-10-2026) documentan un campo deliveryPolicy. Sus valores son auto, verified, official o null. Un valor null hereda la política del Workspace.

Este esquema sigue la forma PATCH documentada. El ID de la key es el valor de ejemplo de la documentación.

curl -X PATCH "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456" \
  -H "Authorization: Bearer mt-your-management-token" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryPolicy": "verified"
  }'

La actualización requiere al menos un campo, por lo que este cuerpo es válido por sí mismo. Las respuestas informan el ajuste como delivery_policy, donde null significa que la key hereda el valor predeterminado del Workspace. El endpoint de creación acepta el mismo campo deliveryPolicy en el cuerpo de su solicitud. Omitirlo al crear es consistente con la herencia null documentada, ya que la respuesta de ejemplo de creación muestra delivery_policy: null.

Cuando la opción solicitada no está disponible

Si la opción que solicitas no tiene suministro, TokenLab devuelve un 503 delivery_tier_unavailable y un ID de solicitud. La guía de manejo de errores (observada el 03-10-2026) explica cómo leer retryable.

Un estado 5xx no siempre significa una interrupción temporal. Cuando la operación seleccionada no tiene suministro en ese nivel, retryable es false y retry_after se omite. No repitas la misma solicitud sin cambios. En su lugar:

1. Lee code y retryable, no el message legible para humanos.
2. Guarda el ID de solicitud de los encabezados de respuesta.
3. Verifica la disponibilidad de entrega del modelo con GET /v1/models antes de elegir otro modelo o nivel.

La guía advierte que nombres de modelos similares no garantizan la disponibilidad. Un cliente debe ramificarse según el code y reintentar un 5xx solo cuando retryable sea true, respetando retry_after y limitando los intentos.

Verificar qué opciones tiene un modelo

El endpoint de modelos informa la delivery availability by option. Estos valores provienen de la API de modelos en vivo, observados el 03-10-2026:

ID del modelo	Verified	Official	Página del modelo
claude-sonnet-5	true	true	/models/claude-5/claude-sonnet-5
gpt-5.6-terra	true	true	/models/gpt-5-6/gpt-5.6-terra
deepseek-v4-flash	false	true	/models/deepseek-v4/deepseek-v4-flash

Por ejemplo, fijar verified en deepseek-v4-flash es el tipo de solicitud que daría lugar a delivery_tier_unavailable, porque la API informa que no hay suministro Verified hoy. Official y Auto siguen siendo válidos allí.

Verifica cualquier modelo tú mismo:

curl "https://api.tokenlab.sh/v1/models/deepseek-v4-flash"

La disponibilidad se verifica cuando se ejecuta cada solicitud, y la guía de facturación dice que las etiquetas de entrega describen las opciones admitidas. Trata la API de modelos como una instantánea y vuelve a leerla antes de codificar un nivel fijo.

Cómo afecta la elección a lo que pagas

La guía de facturación (observada el 03-10-2026) dice que cada solicitud completada se cobra una vez, por la opción que produjo el resultado:

• TokenLab Verified utiliza los precios públicos de TokenLab.
• Official utiliza la capa de precios Official basada en el precio público del creador del modelo.
• Auto cobra la opción que complete la solicitud.

Para la generación de pago, la consola muestra una estimación máxima antes de la confirmación, y el Uso (Usage) muestra el cargo final. Cualquier cantidad reservada no utilizada se libera. En la página de Modelos, un guion en la columna de precio de TokenLab significa que actualmente no hay ninguna oferta Verified disponible. No significa que sea gratis.

La guía no documenta ninguna diferencia de precio fija entre Verified y Official, por lo que no afirmaremos ninguna. Para el precio de TokenLab en vivo en claude-sonnet-5, la API de modelos enumera la entrada a 0.9 USD y la salida a 4.5 USD por cada 1M de tokens (precios actualizados el 02-10-2026). Como estimación, 100,000 tokens de entrada más 10,000 tokens de salida es 0.09 + 0.045 = 0.135 USD. Esa cifra utiliza solo el precio de TokenLab enumerado. Lee el precio Official en la página del modelo antes de comparar.

Una breve guía de decisión

• Usa Auto por defecto cuando quieras que la solicitud se complete y puedas aceptar cualquiera de las dos capas de precios.
• Fija Verified cuando necesites los precios de TokenLab y el modelo informe verified: true.
• Fija Official cuando necesites la base de precio público del creador del modelo, o cuando el modelo no tenga suministro Verified.
• Establece el valor predeterminado de la key para los trabajadores que siempre necesiten el mismo nivel, y usa el encabezado para excepciones puntuales.

Antes de fijar, lee GET /v1/models/{model}. Realiza una pequeña prueba y confirma el cargo en Uso (Usage).

Siguiente paso: crear una key con una política de entrega

Crea una API key en la Consola, o llama a POST /v1/management/api-keys con un token de gestión y establece deliveryPolicy en el cuerpo, como se describe en la página Create API Key. Luego, envía una pequeña solicitud con el encabezado mencionado anteriormente y verifica el cargo en Uso (Usage).

Preguntas frecuentes

¿Qué ajuste gana si el encabezado, la API key y el Workspace no coinciden?

El encabezado de la solicitud gana. El ajuste de la API key anula el valor predeterminado del Workspace. Las sesiones en tiempo real omiten el encabezado y utilizan el ajuste de la key o del Workspace.

¿Por qué obtuve 503 delivery_tier_unavailable y debería reintentar?

El nivel que solicitaste no tiene suministro para esa operación. Lee retryable: cuando sea false, no vuelvas a enviar la misma solicitud. Verifica la disponibilidad con GET /v1/models y cambia el nivel o el modelo.

¿Cuesta más Official que TokenLab Verified?

Los documentos no establecen una diferencia fija. Verified utiliza los precios públicos de TokenLab, y Official utiliza la base de precio público del creador del modelo. Compara ambos en la página del modelo y confirma el cargo final en Uso (Usage).

¿Cómo veo qué opciones de entrega admite un modelo?

Llama a GET /v1/models/{model}, que no requiere ninguna key. Hoy, claude-sonnet-5 y gpt-5.6-terra informan Verified y Official, mientras que deepseek-v4-flash informa solo Official.

¿Puedo establecer una opción de entrega para sesiones en tiempo real?

Sí, a través de la API key o el ajuste del Workspace. Las sesiones en tiempo real no aceptan una anulación mediante cadena de consulta.

Crea tu API key de TokenLab en la Consola