Api.Airforce
API REFERENCE

Завершения чата

Создавайте ответы в чате для более чем 100 моделей с помощью одного API. Модуль, совместимый с завершениями чата OpenAI, антропными сообщениями и антропными ответами.

Аутентификация

Для каждого запроса требуется токен носителя (ваш ключ API Airforce). Антропный x-api-key заголовок также принимается /v1/messages для совместимости с SDK.

Authorization: Bearer sk-air-YOUR_API_KEY
# alt for /v1/messages:
x-api-key: sk-air-YOUR_API_KEY

POST /v1/chat/completions

OpenAI-совместимые завершения чата. Работает с официальным openai SDK путем переопределения base_url к https://api.airforce/v1.

POSThttps://api.airforce/v1/chat/completions

Тело запроса

ParameterTypeRequiredDescription
modelstringRequiredИдентификатор модели. Используйте GET /v1/models, чтобы обнаружить доступные идентификаторы.
messagesarrayRequiredИстория разговора. Каждая запись имеет { роль: "система" | "пользователь" | "помощник" | «инструмент», содержание }. Контент — это строка или массив блоков контента (видение см. ниже).
max_tokensintegerOptionalМаксимальное количество токенов для генерации. Ограничено max_output_tokens модели.
temperaturefloatOptionalТемпература отбора проб, 0–2. Нижний уровень более детерминирован. Значение по умолчанию зависит от вышестоящего провайдера.
top_pfloatOptionalОтбор проб ядра. Используйте либо температуру, либо top_p, но не оба одновременно.
streambooleanOptionalЕсли это правда, ответ представляет собой поток событий, отправленных сервером. См. «Потоковое вещание» ниже.
stream_optionsobjectOptional{include_usage: логическое значение}. Если параметр include_usage имеет значение true, последний фрагмент SSE содержит блок использования.
stopstring | arrayOptionalДо 4 стоп-последовательностей. Генерация прекращается, как только он будет произведен.
toolsarrayOptionalОпределения функций, которые может вызывать модель. См. «Вызов инструмента» ниже.
tool_choicestring | objectOptional«auto» (по умолчанию), «none» или { type: «function», function: { name } } для принудительного выполнения определенного вызова.
response_formatobjectOptional{ type: "json_object" } заставляет модель выдавать действительный JSON. Игнорируется для моделей, которые его не поддерживают.
reasoning_effortstringOptionalГлубина рассуждений в стиле OpenAI o1/o3: «низкая» | "средний" | "высокий". См. «Рассуждение и мышление».
thinkingstring | objectOptionalПереключатель мышления между поставщиками услуг. "на" | "выключено" | «авто» или «Антропная форма» { type: «enabled», Budget_tokens: N }. См. «Рассуждение и мышление».
thinking_budgetintegerOptionalОграничение токена для трассировки рассуждений модели (если поставщик предоставляет его).
ignore_defaultsbooleanOptionalПропустите сохраненные пользователем параметры по умолчанию для каждой модели (настроенные на панели управления) для этого запроса.

Базовый пример

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1-chat",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "max_tokens": 200,
    "temperature": 0.7
  }'

Форма ответа

ParameterTypeRequiredDescription
idstringOptionalСтабильный идентификатор завершения, например. «чатcmpl-abc123».
objectstringOptional«chat.completion» для потоковой передачи, «chat.completion.chunk» для потоковой передачи.
createdintegerOptionalВременная метка Unix (в секундах).
modelstringOptionalЭхо запрошенного идентификатора модели.
choicesarrayOptionalМассив кандидатов на завершение: [{ index, message: { role, content,tool_calls? }, Finish_reason }].
choices[].finish_reasonstringOptional"стоп" | "длина" | "tool_calls" | «контент_фильтр».
usageobjectOptional{ prompt_tokens, completion_tokens, total_tokens, completion_tokens_details?, prompt_tokens_details?, cache_creation_input_tokens?, cache_creation? }. completion_tokens_details.reasoning_tokens устанавливается, когда модель сгенерировала след рассуждений. Поля кеша появляются, когда upstream вернул информацию о prompt-кешировании: prompt_tokens_details.cached_tokens сообщает о чтениях кеша (стандарт OpenAI), cache_creation_input_tokens агрегирует записи, а cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens дают разбивку по TTL.
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-5.1-chat",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The capital of France is Paris."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 8,
    "total_tokens": 28
  }
}

Рассуждение и мышление

Модели, поддерживающие расширенное рассуждение, демонстрируют след мышления наряду с обычным выводом. Airforce нормализует три различных исходных соглашения в один набор канонических параметров, которые работают везде.

Проверять supports_reasoning: true на модели в GET /v1/models чтобы узнать, какие идентификаторы принимают эти параметры.

Модели с аргументированной поддержкой

· live

Канонические параметры

ParameterTypeRequiredDescription
reasoning_effortstringOptional"низкий" | "средний" | "высокий". OpenAI o1/o3, модели рассуждений GPT-5 и любой маршрутизатор, который сопоставляется с ними.
thinkingstring | objectOptional"на" | "выключено" | «auto» для быстрого переключения или { type: «enabled», Budget_tokens: N } для антропной формы. Карты для расширенного мышления Клода, мышления Близнецов и рассуждения DeepSeek.
thinking_budgetintegerOptionalМаксимальное количество жетонов, которые модель может потратить на рассуждения, прежде чем выдать видимый результат. Отражает Budget_tokens.

Усилия по рассуждению (в стиле OpenAI)

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "o3-mini",
    "messages": [{"role": "user", "content": "Prove the Pythagorean theorem."}],
    "reasoning_effort": "high"
  }'

Расширенное мышление (антропный стиль)

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4.6",
    "messages": [{"role": "user", "content": "Plan a 7-day Italy trip."}],
    "thinking": {"type": "enabled", "budget_tokens": 4000}
  }'

Сам след рассуждения проявляется в choices[0].message.reasoning_content (форма OpenAI) или как thinking блокирует в content (Антропная форма). Токены рассуждения выставляются по счетам и сообщаются в usage.completion_tokens_details.reasoning_tokens.


Видение и ввод изображений

Модели с supports_vision: true принимать изображения, встроенные в блоки контента. Подойдет либо общедоступный URL-адрес, либо URL-адрес данных base64; Ограничения по размеру зависят от восходящей модели.

Модели с поддержкой зрения

· live
curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1-chat",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
      ]
    }]
  }'

Вызов инструмента

Модели с supports_tools: true может вызывать функции, которые вы определяете. Модель возвращает tool_calls множество; вы запускаете вызов, а затем отправляете результат обратно в tool сообщение.

Модели с поддержкой вызова инструментов

· live

Запрос

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1-chat",
    "messages": [{"role": "user", "content": "What is the weather in Paris?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

Ответ вызовом инструмента

{
  "id": "chatcmpl-abc123",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_1",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"location\":\"Paris\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Отслеживание результата инструмента

{
  "model": "gpt-5.1-chat",
  "messages": [
    {"role": "user", "content": "What is the weather in Paris?"},
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_1",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{\"location\":\"Paris\"}"}
      }]
    },
    {"role": "tool", "tool_call_id": "call_1", "content": "{\"temp_c\": 14, \"sky\": \"cloudy\"}"}
  ]
}

Потоковое вещание

Набор stream: true для получения частичных завершений как событий, отправленных сервером. Каждое событие представляет собой один фрагмент JSON той же формы, что и непотоковое ответ, за исключением message заменяется на delta. Поток заканчивается data: [DONE].

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1-chat",
    "messages": [{"role": "user", "content": "Write a haiku about Berlin."}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Формат провода

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"gpt-5.1-chat","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"gpt-5.1-chat","choices":[{"index":0,"delta":{"content":"Cold "},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"gpt-5.1-chat","choices":[{"index":0,"delta":{"content":"stone "},"finish_reason":null}]}


data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"gpt-5.1-chat","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":17,"total_tokens":29}}

data: [DONE]

POST /v1/messages

API сообщений, совместимый с Anthropic. Работает с официальным @anthropic-ai/sdk установив baseURL к https://api.airforce. Пересылаем в OpenAI/Google/и т.д. прозрачно для моделей, отличных от Claude.

POSThttps://api.airforce/v1/messages

Тело запроса

ParameterTypeRequiredDescription
modelstringRequiredИдентификатор модели (в формате Anthropic или маршрутизируемый псевдоним).
messagesarrayRequiredКаждая запись: { роль: «пользователь» | «помощник», содержимое: строка | множество }.
max_tokensintegerRequiredТребуется Anthropic. Ограничение токена для ответа.
systemstring | arrayOptionalСистемная подсказка. Передайте массив { type: "text", text,cache_control? } блоки для обозначения сегментов кэшированного префикса. См. «Быстрое кэширование».
temperaturefloatOptional0–1.
top_pfloatOptionalОтбор проб ядра.
top_kintegerOptionalОграничьте пул выборки токенами из топ-K.
stop_sequencesarrayOptionalДо 4 стоп-последовательностей.
streambooleanOptionalЕсли установлено значение true, генерирует поток событий SSE в стиле Anthropic (см. «Потоковая передача»).
toolsarrayOptionalОпределения антропных инструментов: {имя, описание, входная_схема}. Ответ может содержать блоки контентаtool_use.
tool_choiceobjectOptional{ тип: «авто» | "любой" | "инструмент", имя? }.
thinkingobjectOptionalАнтропное расширенное мышление: { type: «enabled», Budget_tokens: N }.

Пример

curl https://api.airforce/v1/messages \
  -H "x-api-key: sk-air-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4.6",
    "max_tokens": 256,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

Форма ответа

ParameterTypeRequiredDescription
idstringOptionalИдентификатор сообщения, например. «msg_01ABCxyz».
typestringOptionalВсегда «сообщение».
rolestringOptionalВсегда «помощник».
contentarrayOptionalМассив блоков контента: { type: "text" | "инструмент_использование" | «мышление», … }.
modelstringOptionalЭхо запрошенной модели.
stop_reasonstringOptional"конец_поворота" | "макс_токены" | "стоп_последовательность" | «инструмент_использование».
usageobjectOptional{ input_tokens, output_tokens, cache_read_input_tokens?, cache_creation_input_tokens?, cache_creation? }. Поля кеша появляются при использовании prompt-кеширования. cache_creation.ephemeral_5m_input_tokens и ephemeral_1h_input_tokens дают разбивку записей по TTL.

Потоковое вещание событий

Anthropic SSE использует именованные события вместо одноразовых фрагментов JSON. Каждое событие имеет как event: имя и data: Полезная нагрузка JSON.

event: message_start
data: {"type":"message_start","message":{"id":"msg_01","role":"assistant","content":[],"model":"claude-sonnet-4.6","stop_reason":null,"usage":{"input_tokens":12,"output_tokens":1}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":17}}

event: message_stop
data: {"type":"message_stop"}

Оперативное кэширование

На /v1/messages с моделями Claude пометьте префикс как кэшированный, передав system как массив блоков, в которых кэшированный сегмент содержит cache_control: { type: "ephemeral" }. Последующие запросы, начинающиеся с того же префикса, требуют более низкой скорости чтения кэша. Модели с supports_caching: true в /v1/models поддержите это.

Модели с быстрым кэшированием

· live
{
  "model": "claude-sonnet-4.6",
  "max_tokens": 1024,
  "system": [
    {"type": "text", "text": "You are a senior staff engineer at Airforce."},
    {
      "type": "text",
      "text": "<repository-snapshot>...</repository-snapshot>",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [
    {"role": "user", "content": "Where is rate limiting enforced?"}
  ]
}

Как счётчики кеша отображаются в ответе

Счётчики токенов кеша передаются в нативной форме каждого формата, поэтому SDK (openai, @anthropic-ai/sdk, @google/genai) читают их без специального кода. Поля опускаются при нулевом значении, сохраняя ответы без кеша компактными.

/v1/chat/completions (форма OpenAI)

"usage": {
  "prompt_tokens": 2104,
  "completion_tokens": 147,
  "total_tokens": 2251,
  "prompt_tokens_details": { "cached_tokens": 1980 },
  "cache_creation_input_tokens": 124,
  "cache_creation": {
    "ephemeral_5m_input_tokens": 124,
    "ephemeral_1h_input_tokens": 0
  }
}

/v1/messages (форма Anthropic)

"usage": {
  "input_tokens": 2104,
  "output_tokens": 147,
  "cache_read_input_tokens": 1980,
  "cache_creation_input_tokens": 124,
  "cache_creation": {
    "ephemeral_5m_input_tokens": 124,
    "ephemeral_1h_input_tokens": 0
  }
}

/v1beta/.../generateContent (форма Gemini)

"usageMetadata": {
  "promptTokenCount": 2104,
  "candidatesTokenCount": 147,
  "totalTokenCount": 2251,
  "cachedContentTokenCount": 1980
}

Где применяется кэширование

Явные маркеры cache_control учитываются на /v1/messages и /v1/chat/completions для моделей Claude — ставьте их на блоки контента system или message. Многие другие провайдеры (семейство OpenAI, DeepSeek, Gemini) кэшируют автоматически: вы не отправляете маркеры и просто видите cached_tokens в ответе, как только переиспользуется достаточно длинный префикс.

Длительность кэша: 5 минут или 1 час

Кэшированный префикс по умолчанию живёт 5 минут, и таймер обновляется при каждом попадании. Для более долгоживущего префикса добавьте ttl: "1h" в маркер. Ответ сообщает каждый TTL отдельно в cache_creation.

"cache_control": { "type": "ephemeral", "ttl": "1h" }

Пример: сначала запись, потом чтение

Отправьте один и тот же запрос дважды (пример кэширования выше). Первый вызов, увидевший префикс, оплачивает однократную запись в кэш; идентичные вызовы в пределах TTL оплачивают гораздо более дешёвое чтение из кэша.

Первый вызов — запись в кэш (фрагмент usage):

"usage": {
  "input_tokens": 2104,
  "output_tokens": 12,
  "cache_creation_input_tokens": 1980,
  "cache_read_input_tokens": 0
}

Второй идентичный вызов в пределах TTL — чтение из кэша:

"usage": {
  "input_tokens": 2104,
  "output_tokens": 12,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 1980
}

Ограничения и стоимость

  • Claude требует минимальный кэшируемый префикс (около 1024 токенов; для некоторых моделей больше). Более короткие префиксы просто не кэшируются.
  • До 4 точек кэширования на запрос, и кэшированный префикс должен быть байт-в-байт идентичным между вызовами — даже изменение одного символа промахивается мимо кэша.
  • Записи в кэш стоят дороже обычного ввода (5m ≈ 1,25×, 1h ≈ 2×); чтения стоят гораздо меньше (≈ 0,1×). Цены кэша по каждой модели — на странице тарифов.

POST /v1/responses

OpenAI Responses-API для stateful диалогов. Та же Bearer/x-api-key аутентификация. Счётчики кеша появляются как input_tokens_details.cached_tokens (чтение) плюс плоский cache_creation_input_tokens + cache_creation.ephemeral_* (записи) для паритета с /v1/chat/completions.

POSThttps://api.airforce/v1/responses

Ошибки

Airforce возвращает стандартные коды состояния HTTP и единый конверт ошибок для обеих конечных точек.

ParameterTypeRequiredDescription
400invalid_requestOptionalНеверный формат JSON, отсутствует обязательное поле, неизвестная модель.
401authentication_errorOptionalКлюч API отсутствует или недействителен.
403permission_errorOptionalПлановые разрешения или разрешения для каждого ключа отклоняют этот запрос.
429rate_limitOptionalПревышена частота запросов или дневной лимит токенов.
503upstream_errorOptionalНе удалось выполнить все восходящие ключи для запрошенного поставщика.
{
  "error": {
    "message": "Model 'gpt-99' not found.",
    "type": "invalid_request",
    "param": "model",
    "code": "model_not_found"
  }
}

Откройте для себя модели

Полный список идентификаторов моделей и флагов их возможностей (видение, инструменты, рассуждения, кэширование, длина контекста и т. д.) см. на странице /docs/api/models.

curl https://api.airforce/v1/models \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY"