API Chat Completions — AiHummer Документация

AiHummer предоставляет единый OpenAI-совместимый HTTP-эндпоинт для текстовых ходов: POST /v1/chat/completions. Любой клиент или SDK, уже умеющий работать с форматом OpenAI Chat Completions, может обращаться к AiHummer, поменяв только базовый URL и ключ — никакого специфичного для AiHummer кода не нужно.

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

Запросы аутентифицируются персональным API-ключом в виде Bearer-токена. Ключи AiHummer имеют префикс ah- и выпускаются в веб-админке.

POST /v1/chat/completions HTTP/1.1
Host: your-aihummer.example
Authorization: Bearer ah-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

[!TIP] Базовый URL — это адрес вашего gateway. В установке по умолчанию gateway слушает на :8765, поэтому локальный вызов идёт на http://localhost:8765/v1/chat/completions. В продакшене TLS терминируется на обратном прокси перед gateway.

Простой запрос

Отправьте JSON-тело с полем messages — ровно так же, как в OpenAI. Поле model выбирает модель (или агента), настроенную на вашем инстансе.

curl https://your-aihummer.example/v1/chat/completions \
  -H "Authorization: Bearer ah-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      { "role": "system", "content": "Ты полезный ассистент." },
      { "role": "user", "content": "Кратко опиши нашу политику возвратов в двух предложениях." }
    ],
    "temperature": 0.3
  }'

Нестриминговый ответ имеет привычную форму Chat Completions:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "default",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Возврат оформляется в течение 14 дней..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 }
}

Стриминг ответов (SSE)

Установите "stream": true, чтобы получать ответ по частям как Server-Sent Events. Каждое событие несёт дельту chat.completion.chunk, а поток завершается финальной строкой data: [DONE].

curl -N https://your-aihummer.example/v1/chat/completions \
  -H "Authorization: Bearer ah-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Напиши приветствие в одну строку." }
    ]
  }'

Ответ — это text/event-stream:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"}}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Привет"}}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":"stop"}]}

data: [DONE]

[!WARNING] /v1/chat/completions — единственный эндпоинт на OpenAI-совместимой поверхности. AiHummer не предоставляет /v1/models и не предоставляет /v1/embeddings — эмбеддинги это внутренняя подсистема, недоступная по HTTP. Не полагайтесь на эти маршруты: они возвращают 404.

Discovery- и schema-поверхности

Хотя листинга /v1/models нет, AiHummer поставляет несколько discovery-поверхностей, чтобы люди и инструменты могли изучать API:

Путь	Что отдаёт
`GET /docs`	Точка входа в документацию для человека
`GET /docs/api`	Интерактивный API Explorer
`GET /docs/openapi.json`	Спецификация OpenAPI 3.x
`GET /openapi.json`	Спецификация OpenAPI 3.x (алиас в корне)
`GET /docs/llm.json`	Машиночитаемая сводка API для LLM-инструментов
`GET /llms.txt`	Индекс `llms.txt` для LLM-агентов

# Получить спецификацию OpenAPI
curl https://your-aihummer.example/openapi.json

Системные эндпоинты

Два лёгких неаутентифицированных системных эндпоинта помогают проверять живость и часы:

Метод и путь	Назначение
`GET /v1/ping`	Простой ответ о живости
`GET /v1/time`	Текущее серверное время gateway

curl https://your-aihummer.example/v1/ping
curl https://your-aihummer.example/v1/time

Куда дальше

Управление AiHummer из своих приложений и автоматизаций: Входящие и интеграционные триггеры.
Pairing, федерация SSO и протокольные поверхности: Вебхуки, SCIM и pairing.
Настройка возможностей агента: Каталог инструментов.