Grupos de canales
Claude · Value, GPT · Value y Gemini · Value reúnen capacidad para cada familia a mitad del precio de lista. Cómo elegir uno por clave o por petición.
Tres grupos de canales atienden todas las llamadas en Half Off Dev, uno por familia de modelos. Cada uno reúne capacidad de varios canales (fuentes individuales de capacidad) que sirven los mismos modelos a un mismo precio. Los tres facturan a la mitad del precio de lista oficial, así que el grupo que te toque nunca cambia lo que pagas.
La mayoría de desarrolladores no toca nunca este ajuste. Una clave nueva empieza en Auto, que envía cada petición al grupo que sirve su modelo. Sigue leyendo si quieres fijar una clave o una petición a un grupo concreto, o saber qué grupo respondió.
Los tres grupos#
| Id del grupo | Nombre | Sirve | Multiplicador |
|---|---|---|---|
claude-value | Claude · Value | Modelos Claude | ×0.50 |
gpt-value | GPT · Value | Modelos GPT | ×0.50 |
gemini-value | Gemini · Value | Modelos Gemini | ×0.50 |
Cada grupo junta varios canales para ganar rendimiento y mantiene cada conversación en un mismo canal, de modo que su caché de prompts sigue caliente entre turnos (consulta Caché de prompts). El campo groups de GET /v1/models indica el grupo de cada modelo, y el catálogo muestra todos los grupos con su multiplicador actual.
Cómo se elige el grupo#
Una petición acaba en un grupo de una de estas tres formas:
| Configuración | Grupo que atiende la llamada |
|---|---|
| Clave en Auto, sin cabecera | El grupo que sirve el modelo pedido. |
Clave en Auto, con cabecera x-halfoff-group | El grupo indicado en la cabecera. |
| Clave vinculada a un grupo | Siempre el grupo de la clave; cualquier cabecera se ignora. |
Como cada familia tiene exactamente un grupo, Auto ya elige el correcto. Vincular una clave sirve para limitarla a una sola familia, por ejemplo una clave que das a un asistente de programación que solo debe llamar a Claude: las peticiones a otros modelos fallan entonces con 404 en lugar de atenderse.
Vincula una clave#
Al crear una clave en Claves de API, elige en Grupo de canales uno de los tres grupos. A partir de ahí, toda petición hecha con esa clave va a ese grupo, pida lo que pida. El vínculo no se puede editar después; crea una clave nueva si necesitas otro. Más sobre los ajustes de clave en Claves de API.
Elige un grupo por petición#
Con una clave en Auto, añade la cabecera x-halfoff-group con el id de un grupo. Se respeta en todos los endpoints de modelos y en los tres formatos de API.
curl https://halfoff.dev/v1/messages \
-H "x-api-key: $HALFOFF_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "x-halfoff-group: claude-value" \
-H "content-type: application/json" \
-d '{"model": "claude-haiku-5.5", "max_tokens": 256,
"messages": [{"role": "user", "content": "Saluda en portugués."}]}'Los SDK de OpenAI aceptan la misma opción default_headers / defaultHeaders.
| Si… | Obtienes |
|---|---|
| La clave está vinculada a un grupo | La cabecera se ignora y responde el grupo de la clave. |
| El id de grupo no existe | 400 con Unknown group '<id>'. |
El grupo no sirve ese modelo en tu formato de API (por ejemplo, gpt-value con un modelo Claude) | 404 con Model '<id>' is not served in <format> format in group '<group>'. |
Qué grupo respondió#
Las respuestas correctas llevan dos cabeceras que te lo dicen:
| Cabecera | Ejemplo |
|---|---|
x-halfoff-group | claude-value |
x-halfoff-channel | Pooled%20capacity (la etiqueta de canal del grupo, codificada para URL) |
El grupo también queda registrado para cada llamada en Registros, donde puedes filtrar por él.
Conmutación por error dentro del grupo#
Si un canal falla o está lleno, el gateway reintenta en otro canal. Con una clave vinculada o una cabecera x-halfoff-group, todos los reintentos se quedan en ese grupo, así que ni el grupo ni el precio pueden cambiar sin que lo sepas. En Auto, el reintento va a un grupo que sirva el modelo, y x-halfoff-group siempre indica el que respondió al final. En Límites y conmutación por error se explica cuándo se reintenta.
Cuánto cuesta cada grupo#
Una llamada cuesta el precio de lista del modelo por el multiplicador del grupo que la atendió. Los tres grupos están a ×0.50, así que cada llamada se cobra a mitad del precio de lista, la atienda el grupo que la atienda. El cálculo completo está en Modelos y precios.