halfoff.devДокументация
Получить ключ
Справочник API

Эндпоинты моделей

Справочник запросов и ответов для Messages, Chat Completions, Responses, Gemini и списка моделей в Half Off Dev с заголовками, которые принимает каждый эндпоинт.

Это собственные эндпоинты вендоров, отвечающие по адресу https://halfoff.dev. Тела запросов следуют схеме каждого вендора и передаются без изменений, поэтому в справочнике собраны параметры, которые нужны чаще всего, а за остальным мы отсылаем к документации вендоров. Поведение, общее для всех эндпоинтов, например переключение каналов и кеширование, описано в разделе Как работает шлюз.

Любой эндпоинт принимает ваш ключ как Authorization: Bearer, x-api-key, x-goog-api-key или параметр запроса ?key=. Ошибки используют формат вызванного эндпоинта; см. Ошибки.

Response headers

x-halfoff-request-idstring

Id вызова, например req_6f1c0b9e2d4a47a1b8c3d5e7, он же указан в Логах. Отправляется в успешных ответах и в ошибках ёмкости 429 и 502.

x-halfoff-groupstring

Группа каналов, которая ответила.

x-halfoff-channelstring

Метка канала этой группы в URL-кодировке.

x-halfoff-queued-msinteger

Миллисекунды ожидания ёмкости. Отсутствует, если ожидания не было.

retry-afterinteger

Сколько секунд подождать. Отправляется с ответами 429 из-за лимитов ключа или занятой ёмкости.

Список моделей#

GET/v1/models

Возвращает все модели, которые можно вызвать прямо сейчас, с контекстным окном, ценами и группами каналов, которые их обслуживают. Ключ не нужен. Формат совместим с models.list() в SDK OpenAI и Anthropic. Цены — это то, что списывает Half Off Dev, то есть половина официальной цены. Подробности полей в разделе Модели и цены.

Response fields

dataarray

Одна запись на модель.

has_moreboolean

Всегда false: полный список приходит в одном ответе.

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"
}

Создание сообщения#

POST/v1/messages

Anthropic Messages API. Укажите stream, чтобы получать серверные события. Расширенное мышление, использование инструментов и кеширование промптов работают точно так, как описывает Anthropic. Руководство: Anthropic Messages.

Headers

x-api-keystringОбязательно

Ваш ключ Half Off Dev. Authorization: Bearer тоже принимается.

anthropic-versionstringПо умолчанию 2023-06-01

Передаётся модели.

anthropic-betastring

Передаётся без изменений.

x-halfoff-groupstring

Группа каналов для этого вызова, например claude-value. Игнорируется, если ключ привязан к группе.

x-session-idstring

Стабильный id диалога, чтобы каждый ход шёл на канал, где лежит его кеш.

Body parameters

modelstringОбязательно

Id модели из GET /v1/models, например claude-sonnet-5.5. Варианты вроде claude-sonnet-5-5 разрешаются в ту же модель.

messagesarrayОбязательно

Диалог на данный момент, чередующиеся ходы user и assistant.

max_tokensintegerОбязательно

Максимум токенов, которые может сгенерировать модель.

systemstring or array

Системный промпт. Текстовые блоки принимают cache_control.

streambooleanПо умолчанию false

Передавать ответ серверными событиями.

thinkingobject

Настройки расширенного мышления.

output_configobject

Настройки вывода, например effort и format.

toolsarray

Инструменты, которые может вызывать модель.

tool_choiceobject

Как модель выбирает инструмент.

metadataobject

Метаданные запроса.

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": "Suggest a name for a budget tracking app."}]
  }'
Response
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {"type": "text", "text": "How about \"Pennywise\"?"}
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 16,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "output_tokens": 9
  }
}

Подсчёт токенов сообщения#

POST/v1/messages/count_tokens

Оценивает, сколько входных токенов использовал бы запрос Messages, не выполняя его. Бесплатно и работает даже при нулевом балансе. Число приблизительное: подходит для проверки контекстного окна и планирования бюджета, а фактическое списание определяется usage настоящего вызова. См. руководство Anthropic по подсчёту токенов.

Headers

x-api-keystringОбязательно

Ваш ключ Half Off Dev. Authorization: Bearer тоже принимается.

x-halfoff-groupstring

Группа каналов, в которой нужно проверить модель. Игнорируется, если ключ привязан к группе.

Body parameters

modelstringОбязательно

Id модели, как для POST /v1/messages.

messagesarrayОбязательно

Сообщения для подсчёта.

systemstring or array

Системный промпт, который нужно учесть.

toolsarray

Определения инструментов, которые нужно учесть.

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": "How long is this prompt?"}]}'
Response
{
  "input_tokens": 15
}

Создание chat completion#

POST/v1/chat/completions

OpenAI Chat Completions API. В этом формате отвечает любая модель из GET /v1/models, включая Claude и Gemini. Потоковые запросы всегда получают stream_options.include_usage: true, так что последний фрагмент содержит usage. Руководство: OpenAI Chat Completions.

Headers

AuthorizationstringОбязательно

Bearer и ваш ключ Half Off Dev.

openai-betastring

Передаётся без изменений.

x-halfoff-groupstring

Группа каналов для этого вызова, например gpt-value. Игнорируется, если ключ привязан к группе.

x-session-idstring

Стабильный id диалога, чтобы каждый ход шёл на канал, где лежит его кеш.

Body parameters

modelstringОбязательно

Id модели из GET /v1/models, например gpt-6.1-sol.

messagesarrayОбязательно

Диалог на данный момент: сообщения system или developer, user, assistant и tool.

streambooleanПо умолчанию false

Передавать серверные события, завершающиеся data: [DONE].

max_completion_tokensinteger

Предел генерируемых токенов, включая токены рассуждений.

reasoning_effortstring

Насколько усердно думает модель с рассуждением. Допустимые значения зависят от модели.

toolsarray

Функции, которые может вызывать модель.

tool_choicestring or object

Как модель выбирает функцию.

response_formatobject

Запросить вывод в JSON или по JSON Schema.

prompt_cache_keystring

Повышает долю попаданий в кеш; используется также как id диалога для маршрутизации.

userstring

Id вашего конечного пользователя. Используется как id диалога, если не передано ничего более конкретного.

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": "Translate \"good morning\" into French."}]
  }'
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": 15,
    "completion_tokens": 3,
    "total_tokens": 18,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 0}
  }
}

Создание ответа#

POST/v1/responses

OpenAI Responses API, который использует Codex CLI. Только модели GPT; любая другая модель возвращает 404. Между вызовами ничего не сохраняется, поэтому каждый раз отправляйте весь диалог в input. Руководство: OpenAI Chat Completions.

Headers

AuthorizationstringОбязательно

Bearer и ваш ключ Half Off Dev.

openai-betastring

Передаётся без изменений.

x-halfoff-groupstring

Группа каналов для этого вызова, например gpt-value. Игнорируется, если ключ привязан к группе.

x-session-idstring

Стабильный id диалога, чтобы каждый ход шёл на канал, где лежит его кеш.

Body parameters

modelstringОбязательно

Id модели GPT из GET /v1/models, например gpt-6.1-sol.

inputstring or arrayОбязательно

Промпт или диалог в виде списка входных элементов.

instructionsstring

Системные инструкции. Ответ возвращает их обратно или null.

streambooleanПо умолчанию false

Передавать типизированные серверные события, завершающиеся response.completed, который содержит usage.

max_output_tokensinteger

Предел генерируемых токенов, включая токены рассуждений.

reasoningobject

Настройки рассуждения, например effort. Допустимые значения зависят от модели.

toolsarray

Функции и другие инструменты, которые может вызывать модель.

storeboolean

Отправляйте false: ответы не сохраняются для последующего получения.

prompt_cache_keystring

Повышает долю попаданий в кеш; используется также как id диалога для маршрутизации.

curl https://halfoff.dev/v1/responses \
  -H "Authorization: Bearer $HALFOFF_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "input": "Give me a one-line git tip.",
    "store": false
  }'

Генерация контента#

POST/v1beta/models/{model}:generateContent

Gemini API. Руководство: Gemini.

Path parameters

modelstringОбязательно

Id модели, например gemini-3.1-pro. Написания Google вроде gemini-3.1-pro-preview разрешаются в ту же модель.

Headers

x-goog-api-keystringОбязательно

Ваш ключ Half Off Dev. Authorization: Bearer или параметр запроса ?key= тоже работают.

x-halfoff-groupstring

Группа каналов для этого вызова, например gemini-value. Игнорируется, если ключ привязан к группе.

x-session-idstring

Стабильный id диалога, чтобы каждый ход шёл на канал, где лежит его кеш.

Body parameters

contentsarrayОбязательно

Диалог на данный момент в виде ходов user и model, составленных из parts.

systemInstructionobject

Системная инструкция в виде объекта контента с текстовыми частями.

generationConfigobject

Настройки вывода: maxOutputTokens, temperature, responseMimeType, thinkingConfig и другие.

toolsarray

Объявления функций и другие инструменты.

toolConfigobject

Как модель выбирает функции.

safetySettingsarray

Пороги безопасности по категориям.

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": "What is a haiku?"}]}]}'
Response
{
  "candidates": [
    {
      "content": {"role": "model", "parts": [{"text": "A haiku is a three-line Japanese poem of 5, 7 and 5 syllables."}]},
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 18,
    "thoughtsTokenCount": 84,
    "totalTokenCount": 107
  },
  "responseId": "mFHoaNC1Lo3HqtsP"
}

Потоковая генерация контента#

POST/v1beta/models/{model}:streamGenerateContent

Тот же запрос, что и generateContent, но ответ приходит потоком. Добавьте alt=sse, чтобы получать серверные события, по одному частичному ответу на событие; SDK добавляют его сами. Без него вы получите один JSON-массив, передаваемый по частям. См. Потоковая передача.

Query parameters

altstring

sse для серверных событий. Рекомендуется.

Параметр пути, заголовки и тело такие же, как в Генерации контента.

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": "List three primary colors."}]}]}'
Response
data: {"candidates":[{"content":{"role":"model","parts":[{"text":"Red, yellow"}]}}],"usageMetadata":{"promptTokenCount":6,"candidatesTokenCount":3,"totalTokenCount":9}}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":" and blue."}]},"finishReason":"STOP"}],"usageMetadata":{"promptTokenCount":6,"candidatesTokenCount":6,"totalTokenCount":12}}

Подсчёт токенов Gemini#

POST/v1beta/models/{model}:countTokens

Оценивает число токенов в contents, не запуская модель. Бесплатно и работает даже при нулевом балансе. Число приблизительное. Справочник Gemini.

Body parameters

contentsarrayОбязательно

Контент для подсчёта в том же формате, что и для generateContent.

Параметр пути и заголовки такие же, как в Генерации контента.

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": "How long is this prompt?"}]}]}'
Response
{
  "totalTokens": 7
}

Список моделей в формате Gemini#

GET/v1beta/models

Перечисляет модели, доступные через эндпоинты Gemini, в формате Gemini API. Ключ не нужен. Google Gen AI SDK вызывают его из models.list(). Цены есть только в 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"]
    }
  ]
}
← Назад
Введение
Справочник API
Далее →
Ошибки
Справочник API