halfoff.devDocs
Obtén una clave
Referencia de la API

Endpoints de modelos

Referencia de peticiones y respuestas de Messages, Chat Completions, Responses, Gemini y la lista de modelos en Half Off Dev, con sus cabeceras.

Estos son los endpoints propios de cada proveedor de modelos, servidos en https://halfoff.dev. Los cuerpos siguen el esquema del proveedor y pasan sin modificaciones, así que esta referencia recoge los parámetros que más vas a usar y enlaza a la documentación oficial para el resto. El comportamiento común a todos, como la conmutación por error y la caché, se explica en Cómo funciona el gateway.

Cualquier endpoint acepta tu clave como Authorization: Bearer, x-api-key, x-goog-api-key o el parámetro de consulta ?key=. Los errores usan el formato del endpoint que llamaste; consulta Errores.

Response headers

x-halfoff-request-idstring

ID de la llamada, como req_6f1c0b9e2d4a47a1b8c3d5e7, también visible en Logs. Se envía en las respuestas correctas y en los errores 429 de capacidad y 502.

x-halfoff-groupstring

El grupo de canales que respondió.

x-halfoff-channelstring

La etiqueta de canal de ese grupo, codificada para URL.

x-halfoff-queued-msinteger

Milisegundos de espera por capacidad. No aparece si no hubo espera.

retry-afterinteger

Segundos que debes esperar. Se envía con las respuestas 429 causadas por límites de la clave o capacidad ocupada.

Listar modelos#

GET/v1/models

Devuelve todos los modelos que puedes usar ahora mismo, con su ventana de contexto, sus precios y los grupos de canales que los sirven. No necesita clave. El formato es compatible con models.list() de los SDK de OpenAI y de Anthropic. Los precios son los que cobra Half Off Dev, la mitad del precio oficial. El detalle de cada campo está en Modelos y precios.

Response fields

dataarray

Un elemento por modelo.

has_moreboolean

Siempre false: recibes la lista completa en una sola respuesta.

curl https://halfoff.dev/v1/models
Response
{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-5.5",
      "object": "model",
      "type": "model",
      "display_name": "Claude Sonnet 5.5",
      "created": 1700000000,
      "created_at": "2025-01-01T00:00:00Z",
      "owned_by": "Anthropic",
      "context_length": 1000000,
      "pricing": {
        "input": 1,
        "output": 5,
        "cache_read": 0.05,
        "cache_write": 1.25,
        "unit": "USD per 1M tokens"
      },
      "groups": ["claude-value"]
    }
  ],
  "has_more": false,
  "first_id": "claude-fable-5.1",
  "last_id": "gpt-5.6-luna"
}

Crear un mensaje#

POST/v1/messages

La API Messages de Anthropic. Activa stream para recibir server-sent events. El razonamiento extendido, el uso de herramientas y la caché de prompts funcionan tal como los documenta Anthropic. Guía: Anthropic Messages.

Headers

x-api-keystringObligatorio

Tu clave de Half Off Dev. También se acepta Authorization: Bearer.

anthropic-versionstringPredeterminado 2023-06-01

Se reenvía al modelo.

anthropic-betastring

Se reenvía tal cual.

x-halfoff-groupstring

Grupo de canales para esta llamada, por ejemplo claude-value. Se ignora si la clave está ligada a un grupo.

x-session-idstring

ID estable de la conversación, para que cada turno vaya al canal que guarda su caché.

Body parameters

modelstringObligatorio

Un ID de modelo de GET /v1/models, por ejemplo claude-sonnet-5.5. Variantes como claude-sonnet-5-5 apuntan al mismo modelo.

messagesarrayObligatorio

La conversación hasta ahora, alternando turnos user y assistant.

max_tokensintegerObligatorio

Máximo de tokens que puede generar el modelo.

systemstring or array

Prompt de sistema. Los bloques de texto aceptan cache_control.

streambooleanPredeterminado false

Devuelve la respuesta como server-sent events.

thinkingobject

Ajustes de razonamiento extendido.

output_configobject

Ajustes de salida como effort y format.

toolsarray

Herramientas que el modelo puede invocar.

tool_choiceobject

Cómo elige herramienta el modelo.

metadataobject

Metadatos de la petición.

curl https://halfoff.dev/v1/messages \
  -H "x-api-key: $HALFOFF_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5.5",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "Propón un nombre para una app de finanzas personales."}]
  }'
Response
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {"type": "text", "text": "¿Qué tal \"Alcancía\"?"}
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 19,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "output_tokens": 9
  }
}

Contar tokens de un mensaje#

POST/v1/messages/count_tokens

Calcula cuántos tokens de entrada usaría una petición Messages, sin ejecutarla. Es gratis y funciona incluso con saldo cero. El resultado es aproximado: útil para comprobar la ventana de contexto y presupuestar, mientras que el cargo real sale del usage de una llamada real. Consulta la guía de conteo de tokens de Anthropic.

Headers

x-api-keystringObligatorio

Tu clave de Half Off Dev. También se acepta Authorization: Bearer.

x-halfoff-groupstring

Grupo de canales contra el que se comprueba el modelo. Se ignora si la clave está ligada a un grupo.

Body parameters

modelstringObligatorio

ID del modelo, igual que en POST /v1/messages.

messagesarrayObligatorio

Mensajes que contar.

systemstring or array

Prompt de sistema que incluir.

toolsarray

Definiciones de herramientas que incluir.

curl https://halfoff.dev/v1/messages/count_tokens \
  -H "x-api-key: $HALFOFF_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5.5",
       "messages": [{"role": "user", "content": "¿Cuánto mide este prompt?"}]}'
Response
{
  "input_tokens": 15
}

Crear una chat completion#

POST/v1/chat/completions

La API Chat Completions de OpenAI. Todos los modelos de GET /v1/models responden en este formato, Claude y Gemini incluidos. Las peticiones con streaming llevan siempre stream_options.include_usage: true, así que el último fragmento incluye usage. Guía: OpenAI Chat Completions.

Headers

AuthorizationstringObligatorio

Bearer seguido de tu clave de Half Off Dev.

openai-betastring

Se reenvía tal cual.

x-halfoff-groupstring

Grupo de canales para esta llamada, por ejemplo gpt-value. Se ignora si la clave está ligada a un grupo.

x-session-idstring

ID estable de la conversación, para que cada turno vaya al canal que guarda su caché.

Body parameters

modelstringObligatorio

Un ID de modelo de GET /v1/models, por ejemplo gpt-6.1-sol.

messagesarrayObligatorio

La conversación hasta ahora: mensajes system o developer, user, assistant y tool.

streambooleanPredeterminado false

Devuelve server-sent events que terminan con data: [DONE].

max_completion_tokensinteger

Tope de tokens generados, incluidos los de razonamiento.

reasoning_effortstring

Cuánto razona un modelo de razonamiento. Los valores dependen del modelo.

toolsarray

Funciones que el modelo puede invocar.

tool_choicestring or object

Cómo elige función el modelo.

response_formatobject

Pide salida JSON o un JSON Schema.

prompt_cache_keystring

Mejora la tasa de aciertos de caché; también sirve como ID de conversación para el enrutamiento.

userstring

ID de tu usuario final. Se usa como ID de conversación si no envías nada más específico.

curl https://halfoff.dev/v1/chat/completions \
  -H "Authorization: Bearer $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "messages": [{"role": "user", "content": "Traduce \"buenos días\" al francés."}]
  }'
Response
{
  "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
  "object": "chat.completion",
  "created": 1791700000,
  "model": "gpt-6.1-sol",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Bonjour."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 16,
    "completion_tokens": 3,
    "total_tokens": 19,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 0}
  }
}

Crear una respuesta#

POST/v1/responses

La API Responses de OpenAI, la que usa Codex CLI. Solo para modelos GPT; cualquier otro modelo devuelve 404. No se guarda nada entre llamadas, así que envía la conversación completa en input cada vez. Guía: OpenAI Chat Completions.

Headers

AuthorizationstringObligatorio

Bearer seguido de tu clave de Half Off Dev.

openai-betastring

Se reenvía tal cual.

x-halfoff-groupstring

Grupo de canales para esta llamada, por ejemplo gpt-value. Se ignora si la clave está ligada a un grupo.

x-session-idstring

ID estable de la conversación, para que cada turno vaya al canal que guarda su caché.

Body parameters

modelstringObligatorio

Un ID de modelo GPT de GET /v1/models, por ejemplo gpt-6.1-sol.

inputstring or arrayObligatorio

Un prompt, o la conversación como lista de elementos de entrada.

instructionsstring

Instrucciones de sistema. La respuesta las devuelve tal cual, o null.

streambooleanPredeterminado false

Devuelve server-sent events tipados que terminan con response.completed, que incluye usage.

max_output_tokensinteger

Tope de tokens generados, incluidos los de razonamiento.

reasoningobject

Ajustes de razonamiento como effort. Los valores dependen del modelo.

toolsarray

Funciones y otras herramientas que el modelo puede invocar.

storeboolean

Envía false: las respuestas no se guardan para recuperarlas después.

prompt_cache_keystring

Mejora la tasa de aciertos de caché; también sirve como ID de conversación para el enrutamiento.

curl https://halfoff.dev/v1/responses \
  -H "Authorization: Bearer $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "input": "Dame un truco de git en una línea.",
    "store": false
  }'

Generar contenido#

POST/v1beta/models/{model}:generateContent

La API de Gemini. Guía: Gemini.

Path parameters

modelstringObligatorio

ID del modelo, por ejemplo gemini-3.1-pro. Las variantes de Google como gemini-3.1-pro-preview apuntan al mismo modelo.

Headers

x-goog-api-keystringObligatorio

Tu clave de Half Off Dev. También funcionan Authorization: Bearer o el parámetro ?key=.

x-halfoff-groupstring

Grupo de canales para esta llamada, por ejemplo gemini-value. Se ignora si la clave está ligada a un grupo.

x-session-idstring

ID estable de la conversación, para que cada turno vaya al canal que guarda su caché.

Body parameters

contentsarrayObligatorio

La conversación hasta ahora, como turnos user y model formados por parts.

systemInstructionobject

Instrucción de sistema, como objeto content con partes de texto.

generationConfigobject

Ajustes de salida: maxOutputTokens, temperature, responseMimeType, thinkingConfig y más.

toolsarray

Declaraciones de funciones y otras herramientas.

toolConfigobject

Cómo elige funciones el modelo.

safetySettingsarray

Umbrales de seguridad por categoría.

curl "https://halfoff.dev/v1beta/models/gemini-3.1-pro:generateContent" \
  -H "x-goog-api-key: $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "¿Qué es un haiku?"}]}]}'
Response
{
  "candidates": [
    {
      "content": {"role": "model", "parts": [{"text": "Un haiku es un poema japonés de tres versos de 5, 7 y 5 sílabas."}]},
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 6,
    "candidatesTokenCount": 20,
    "thoughtsTokenCount": 88,
    "totalTokenCount": 114
  },
  "responseId": "mFHoaNC1Lo3HqtsP"
}

Generar contenido en streaming#

POST/v1beta/models/{model}:streamGenerateContent

La misma petición que generateContent, entregada como stream. Añade alt=sse para recibir server-sent events, una respuesta parcial por evento; los SDK lo añaden por ti. Sin él recibes un único array JSON enviado por partes. Consulta Streaming.

Query parameters

altstring

sse para server-sent events. Recomendado.

El parámetro de ruta, las cabeceras y el cuerpo son los mismos que en Generar contenido.

curl -N "https://halfoff.dev/v1beta/models/gemini-3-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Nombra los tres colores primarios."}]}]}'
Response
data: {"candidates":[{"content":{"role":"model","parts":[{"text":"Rojo, amarillo"}]}}],"usageMetadata":{"promptTokenCount":8,"candidatesTokenCount":4,"totalTokenCount":12}}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":" y azul."}]},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":8,"candidatesTokenCount":7,"totalTokenCount":15}}

Contar tokens de Gemini#

POST/v1beta/models/{model}:countTokens

Calcula los tokens de contents sin ejecutar el modelo. Es gratis y funciona incluso con saldo cero. El resultado es aproximado. Referencia de Gemini.

Body parameters

contentsarrayObligatorio

El contenido que contar, con la misma forma que en generateContent.

El parámetro de ruta y las cabeceras son los mismos que en Generar contenido.

curl "https://halfoff.dev/v1beta/models/gemini-3.1-pro:countTokens" \
  -H "x-goog-api-key: $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "¿Cuánto mide este prompt?"}]}]}'
Response
{
  "totalTokens": 8
}

Listar modelos en formato Gemini#

GET/v1beta/models

Lista los modelos disponibles a través de los endpoints de Gemini, con la forma que usa la API de Gemini. No necesita clave. Los SDK Google Gen AI lo llaman desde models.list(). Los precios solo aparecen en GET /v1/models.

cURL
curl https://halfoff.dev/v1beta/models
Response
{
  "models": [
    {
      "name": "models/gemini-3.1-pro",
      "displayName": "Gemini 3.1 Pro",
      "inputTokenLimit": 1048576,
      "supportedGenerationMethods": ["generateContent", "streamGenerateContent", "countTokens"]
    }
  ]
}
← Anterior
Introducción
Referencia de la API
Siguiente →
Errores
Referencia de la API