Один API.
Все ваши модели.

Быстрый старт

Первый запрос за несколько шагов#

Для начала понадобятся аккаунт компании, API-ключ и средства на балансе организации. Примеры ниже выполняются на вашем сервере или компьютере.

export QVORA_API_KEY="shds-ВАШ_КЛЮЧ"

python -m pip install openai

Команды cURL на этой странице используют синтаксис Bash. В Windows запустите их в WSL / Git Bash или выберите пример Python.

curl --fail-with-body "https://qvora.ru/api/v1/chat/completions" \
  -H "Authorization: Bearer $QVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": "Ответь одним словом: привет!"
    }
  ],
  "max_completion_tokens": 1024
}'

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "created": 1790000000,
  "model": "gpt-5-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 4,
    "total_tokens": 22,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  },
  "qvora": {
    "served_model": "gpt-5-mini",
    "cost_rub": 0.1,
    "cache_saved_rub": 0,
    "request_ref": "reservation_example"
  }
}

Авторизация и права ключа#

Передавайте ключ организации в каждом запросе. Основной способ — заголовок Authorization; x-api-key подходит для клиентов Anthropic. Используйте один из вариантов.

Authorization: Bearer shds-ВАШ_КЛЮЧ

GET /models, GET /models/{id} и GET /balance требуют действующий ключ без дополнительного скоупа. OpenAPI-схема доступна без авторизации.

Ключ списывает средства с баланса своей организации. В настройках доступны денежные лимиты, RPM, TPM, число параллельных запросов, разрешённые модели, IP-адреса и срок действия. Изменения применяются следующим запросом. Отзыв действует сразу, при ротации старый ключ по умолчанию живёт ещё 24 часа.

Модели и возможности#

Каталог возвращает текстовые модели и эмбеддинги по прайс-буку вашего контракта. Передавайте data[].id в поле model. Псевдонимы перечислены в qvora.aliases; фактически выбранная модель указана в ответе генерации.

curl --fail-with-body "https://qvora.ru/api/v1/models" \
  -H "Authorization: Bearer $QVORA_API_KEY"

Поддержка возможностей зависит от модели. Для инструментов проверьте tools, для JSON Schema — json_schema, для изображений во входе — vision. Allowlist ключа дополнительно ограничивает запуск. Медиа-модели и параметры их операций доступны в GET /media/models.

Текстовые модели

Chat Completions#

Передайте историю диалога в messages. API возвращает сообщение ассистента, число токенов и стоимость. Историю хранит ваше приложение: в следующем запросе отправьте предыдущие сообщения вместе с новым.

Изображение во входном сообщении

Для анализа изображения используйте image_url в сообщении пользователя. Поддерживаются URL и data: URI. Замените адрес ниже на доступное модели изображение.

curl --fail-with-body "https://qvora.ru/api/v1/chat/completions" \
  -H "Authorization: Bearer $QVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Что изображено на фотографии?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/photo.jpg"
          }
        }
      ]
    }
  ]
}'

Поля ответа

choices[0].finish_reason объясняет завершение: stop — ответ закончен, length — достигнут предел, tool_calls — нужно выполнить инструмент. Поля usage и qvora позволяют сопоставить результат с расходами.

Потоковые ответы#

Установите stream: true, чтобы получать ответ по мере генерации через Server-Sent Events. Для итоговых токенов и стоимости добавьте stream_options.include_usage: true.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["QVORA_API_KEY"],
    base_url="https://qvora.ru/api/v1",
)

stream = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[{"role": "user", "content": "Напиши короткое приветствие."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
    if chunk.usage:
        print("\nТокены:", chunk.usage.total_tokens)

Не разбирайте поток по сетевым пакетам: один JSON может прийти несколькими пакетами. SDK делает сборку событий за вас. Ошибка после начала стрима передаётся внутри потока — проверяйте события, даже если HTTP-статус уже 200.

Разрыв соединения останавливает генерацию; списание рассчитывается по фактически учтённому использованию. При обрыве итоговый чанк может не дойти: проверяйте расход в журнале запросов.

Вызов инструментов и структурированный JSON#

Модель выбирает функцию и формирует аргументы. Ваш сервер выполняет функцию и возвращает результат в следующем запросе. QVORA не запускает код ваших функций.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["QVORA_API_KEY"],
    base_url="https://qvora.ru/api/v1",
)
import json

messages = [{"role": "user", "content": "Где заказ 1042?"}]
tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Узнать статус заказа по номеру",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
            "additionalProperties": False,
        },
    },
}]
first = client.chat.completions.create(
    model="gpt-5-mini", messages=messages, tools=tools,
    tool_choice={"type": "function", "function": {"name": "get_order_status"}},
)
assistant = first.choices[0].message
messages.append(assistant.model_dump(exclude_none=True))
for call in assistant.tool_calls or []:
    if call.function.name != "get_order_status":
        raise ValueError("Неизвестный инструмент")
    args = json.loads(call.function.arguments)
    # Демонстрационные данные. Здесь вызывается ваша система заказов.
    result = {"order_id": args["order_id"], "status": "Передан в доставку"}
    messages.append({
        "role": "tool", "tool_call_id": call.id,
        "content": json.dumps(result, ensure_ascii=False),
    })
final = client.chat.completions.create(
    model="gpt-5-mini", messages=messages, tools=tools, tool_choice="none",
)
print(final.choices[0].message.content)

Сохраняйте tool_calls в сообщении ассистента и передавайте соответствующий tool_call_id в каждом ответе с ролью tool. Проверяйте имя функции, аргументы и права пользователя перед выполнением.

Ответ по JSON Schema

Используйте response_format.type: json_schema и модель с возможностью json_schema. Для JSON без фиксированной схемы есть json_object.

curl --fail-with-body "https://qvora.ru/api/v1/chat/completions" \
  -H "Authorization: Bearer $QVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": "Извлеки город: доставка в Москву."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "delivery",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          }
        },
        "required": [
          "city"
        ],
        "additionalProperties": false
      }
    }
  }
}'

JSON возвращается строкой в choices[0].message.content. Разберите его через JSON.parse или json.loads, предварительно проверив завершение ответа.

Маскировка персональных данных#

Параметр obfuscate скрывает персональные данные до отправки провайдеру и возвращает настоящие значения в ответе — в обычном и потоковом режиме, а также в аргументах tool_calls. Работает одинаково в Chat Completions, Responses и Messages. Бесплатно.

curl --fail-with-body "https://qvora.ru/api/v1/chat/completions" \
  -H "Authorization: Bearer $QVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-5-mini",
  "obfuscate": true,
  "messages": [
    {
      "role": "user",
      "content": "Составь письмо: Иванов Пётр Сергеевич, ИНН 500100732259, тел. +7 916 245-33-18"
    }
  ]
}'

Провайдер получит Иванов Пётр Сергеевич как <<PER0>>, ИНН как <<ID1>>, телефон как <<PHONE2>>; вы получите ответ с исходными значениями. Одинаковые значения в запросе получают одну метку, поэтому модель различает людей и связи между ними. При повторной отправке той же истории метки не меняются, поэтому кэш промпта продолжает работать.

Числа проверяем по контрольным суммам (ИНН, СНИЛС, карта, IBAN) или по слову-подсказке рядом, чтобы не маскировать номера заказов и прочие случайные числа. Ограничить типы можно параметром obfuscate_types, исключить значения — obfuscate_allow.

Свои шаблоны

{
  "obfuscate": true,
  "obfuscate_patterns": [
    {
      "pattern": "ДП-\\d{4}/\\d{4}",
      "label": "CONTRACT"
    },
    {
      "pattern": "EMP-(\\d+)",
      "label": "EMPLOYEE"
    }
  ]
}

До 20 выражений по 500 символов. Если в выражении есть группы, маскируется только их содержимое. Метка: 1–16 символов A–Z, 0–9, _, по умолчанию CUSTOM. Синтаксис JavaScript RegExp; Python-формы (?P<name>…) и (?i) тоже принимаются. Некорректное или слишком медленное выражение — 400 invalid_obfuscate_patterns.

Без изменения тела запроса

Если клиент не даёт добавить поле в тело (Claude Code, Codex, готовые SDK), передайте заголовок x-qvora-obfuscate: placeholder или surrogate. Для Claude Code: ANTHROPIC_CUSTOM_HEADERS="x-qvora-obfuscate: placeholder".

Проверка без модели

curl --fail-with-body "https://qvora.ru/api/v1/pii/detect" \
  -H "Authorization: Bearer $QVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Иванов Пётр, +7 916 245-33-18, договор ДП-2026/0142",
  "mode": "placeholder",
  "patterns": [
    {
      "pattern": "ДП-\\d{4}/\\d{4}",
      "label": "CONTRACT"
    }
  ]
}'

Возвращает masked — текст в том виде, в каком его получит модель, — и список найденного. Бесплатно; значения не журналируются.

Политика организации

В кабинете компании (раздел «Защита данных») владелец или администратор включает маскировку по умолчанию для всех ключей и для чата сотрудников. Режим «Обязательно» нельзя отключить параметром запроса. Изменения политики записываются в журнал аудита.

В ответе qvora.obfuscation и заголовок x-qvora-obfuscation показывают режим и число скрытых значений по типам, без самих значений.

Responses API#

Протокол для client.responses.create и агентных клиентов. В input передайте строку или массив элементов, в instructions — системную инструкцию.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["QVORA_API_KEY"],
    base_url="https://qvora.ru/api/v1",
)

response = client.responses.create(
    model="gpt-5-mini",
    instructions="Отвечай кратко и по-русски.",
    input="Что такое API?",
)
print(response.output_text)

Инструменты имеют плоскую структуру: {type: "function", name, parameters}. Верните результат как function_call_output с исходным call_id. В стриме используйте типы событий response.created, response.output_text.delta и response.completed.

Anthropic Messages#

Для Anthropic SDK используйте Base URL https://qvora.ru/api: SDK сам добавляет /v1/messages. Установите пакет командой python -m pip install anthropic.

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["QVORA_API_KEY"],
    base_url="https://qvora.ru/api",
)
message = client.messages.create(
    model="claude-sonnet", max_tokens=256,
    messages=[{"role": "user", "content": "Привет!"}],
)
for block in message.content:
    if block.type == "text":
        print(block.text)

Поддерживаются блоки text, image, tool_use, tool_result, системная инструкция и поток событий Anthropic. В usage.input_tokens не входят токены cache_read_input_tokens.

POST /messages/count_tokens возвращает бесплатную приблизительную оценку входа. Для расчёта итоговой стоимости используйте фактический usage после генерации.

Эмбеддинги#

Преобразуйте текст в векторы для поиска, сравнения и RAG. Передайте строку или до 2 048 непустых строк; общий размер входа — до 2 млн символов, дополнительно действует контекст модели.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["QVORA_API_KEY"],
    base_url="https://qvora.ru/api/v1",
)

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=["Оплата по счёту", "Как получить закрывающие документы?"],
    encoding_format="float",
)
for item in response.data:
    print(item.index, len(item.embedding))

Результаты находятся в data[].embedding, порядок определяется по index. Поддерживаются encoding_format: float | base64; OpenAI Python SDK умеет декодировать base64 автоматически. dimensions можно задавать для моделей, поддерживающих изменение размерности. Массивы числовых токенов во входе не принимаются.

Оплачиваются только входные токены; минимальное списание — 0,1 ₽ за запрос. Доступные модели имеют qvora.type: embedding в GET /models.

Медиа-задачи

Изображения, видео, музыка и озвучка#

Медиа создаются асинхронно: получите ID задачи, затем опрашивайте её состояние или дождитесь вебхука. Изображения генерируются через /media/tasks, а не через OpenAI Images API.

1. Выберите модель и параметры

curl --fail-with-body "https://qvora.ru/api/v1/media/models/nano-banana" \
  -H "Authorization: Bearer $QVORA_API_KEY"

В operations перечислены операции модели. Объект schemas[operation] содержит JSON Schema для params, допустимые роли inputs, обязательность промпта, формат результата и правило цены price. Значения длительности, голоса и разрешения выбирайте из каталога конкретной модели.

2. Создайте задачу

curl --fail-with-body "https://qvora.ru/api/v1/media/tasks" \
  -H "Authorization: Bearer $QVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "nano-banana",
  "operation": "generate",
  "prompt": "Красный куб на белом фоне, предметная фотография",
  "params": {
    "aspect": "16:9",
    "count": 1
  },
  "idempotency_key": "image-order-1042",
  "wait": 0
}'

{
  "id": "task_example",
  "object": "media.task",
  "status": "queued",
  "model": "nano-banana",
  "served_model": "nano-banana",
  "operation": "generate",
  "created_at": 1790000000,
  "finished_at": null,
  "progress": {
    "done": 0,
    "total": 1
  },
  "request": {
    "model": "nano-banana",
    "operation": "generate",
    "prompt": "Красный куб на белом фоне, предметная фотография",
    "params": {
      "aspect": "16:9",
      "count": 1
    },
    "inputs": {}
  },
  "results": [],
  "error": null,
  "cost": {
    "charged_rub": 13,
    "refunded_rub": 0,
    "currency": "RUB"
  },
  "webhook_url": null,
  "idempotency_key": "image-order-1042"
}

wait — необязательное ожидание до 60 секунд. Даже если задача завершилась за это время, новый запрос возвращает 202; всегда проверяйте поле status. Повтор с тем же idempotency_key и телом возвращает ту же задачу с 200.

3. Получите результат

curl --fail-with-body "https://qvora.ru/api/v1/media/tasks/task_example" \
  -H "Authorization: Bearer $QVORA_API_KEY"

Терминальные статусы — succeeded, failed, cancelled. При успехе заберите файлы из results[].url; при ошибке проверьте error и cost.refunded_rub. Для нескольких результатов сверяйте списание и возврат по задаче.

import json
import os
import time
import uuid
from urllib.request import Request, urlopen

base = "https://qvora.ru/api/v1"
headers = {
    "Authorization": "Bearer " + os.environ["QVORA_API_KEY"],
    "Content-Type": "application/json",
}
body = {
    "model": "nano-banana", "operation": "generate",
    "prompt": "Красный куб на белом фоне",
    "params": {"aspect": "16:9", "count": 1},
    "idempotency_key": str(uuid.uuid4()),
}
# Сохраните body с ключом, чтобы безопасно повторить POST при обрыве связи.
request = Request(base + "/media/tasks", data=json.dumps(body).encode(), headers=headers)
with urlopen(request, timeout=90) as response:
    task = json.load(response)
print("Задача:", task["id"])

deadline = time.monotonic() + 600
while task["status"] in ("queued", "running"):
    if time.monotonic() >= deadline:
        raise TimeoutError("Продолжите опрос задачи " + task["id"])
    time.sleep(5)
    request = Request(base + "/media/tasks/" + task["id"], headers=headers)
    with urlopen(request, timeout=30) as response:
        task = json.load(response)
if task["status"] != "succeeded":
    raise RuntimeError(task.get("error") or task["status"])
for result in task["results"]:
    print(result["url"], "действует до", result["expires_at"])

Редактирование изображения

Передайте исходник в inputs.image. Все URL в примерах замените на свои публичные HTTPS-адреса.

curl --fail-with-body "https://qvora.ru/api/v1/media/tasks" \
  -H "Authorization: Bearer $QVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "nano-banana",
  "operation": "edit",
  "prompt": "Сделай фон белым, сохрани предмет без изменений",
  "inputs": {
    "image": "https://example.com/product.jpg"
  },
  "params": {
    "aspect": "1:1",
    "count": 1
  },
  "idempotency_key": "edit-order-1042"
}'

Вебхуки#

Добавьте webhook_url при создании медиа-задачи. После завершения QVORA отправит POST на публичный HTTPS-адрес с событием media.task.succeeded, media.task.failed или media.task.cancelled.

{
  "id": "evt_example",
  "type": "media.task.succeeded",
  "created_at": 1790000060,
  "data": {
    "id": "task_example",
    "object": "media.task",
    "status": "succeeded",
    "model": "nano-banana",
    "served_model": "nano-banana",
    "operation": "generate",
    "created_at": 1790000000,
    "finished_at": 1790000060,
    "progress": {
      "done": 1,
      "total": 1
    },
    "request": {
      "model": "nano-banana",
      "operation": "generate",
      "prompt": "Красный куб на белом фоне, предметная фотография",
      "params": {
        "aspect": "16:9",
        "count": 1
      },
      "inputs": {}
    },
    "results": [
      {
        "type": "image",
        "url": "https://files.example.com/result.png",
        "preview_url": null,
        "thumbnail_url": null,
        "expires_at": 1790003660
      }
    ],
    "error": null,
    "cost": {
      "charged_rub": 13,
      "refunded_rub": 0,
      "currency": "RUB"
    },
    "webhook_url": "https://example.com/hooks/qvora",
    "idempotency_key": "image-order-1042"
  }
}

Проверка подписи

Секрет webhook_secret выдаётся при создании ключа через Admin API. Получить новый можно через POST /admin/keys/{id}/webhook-secret: старый секрет сразу перестанет действовать. Подписывается строка timestamp + "." + rawBody.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody — исходный Buffer HTTP-запроса, до JSON.parse().
export function verifyWebhook(secret, signature, rawBody) {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(signature ?? "");
  if (!match) return false;
  const timestamp = Number(match[1]);
  const now = Math.floor(Date.now() / 1000);
  if (!Number.isFinite(timestamp) || Math.abs(now - timestamp) > 300) {
    return false;
  }
  const expected = createHmac("sha256", secret)
    .update(match[1] + ".")
    .update(rawBody)
    .digest();
  return timingSafeEqual(expected, Buffer.from(match[2], "hex"));
}

Проверяйте исходные байты до JSON-разбора. Например, в Express используйте express.raw({type: "application/json"}) на маршруте вебхука до общего express.json(). После успешной проверки разберите тело и надёжно сохраните событие.

Верните 2xx в течение 10 секунд после приёма события. При сбое или другом статусе доставка повторяется через 5 с, 20 с, 1, 3, 10 и 30 минут. Обработка должна выдерживать дубли: сохраняйте уникальную пару data.id + type. Для истёкшей ссылки на результат повторно запросите задачу.

История: GET /media/tasks/{id}/webhooks. Повтор вручную: POST /admin/webhooks/deliveries/{id}/retry со скоупом admin.

Транскрибация аудио#

Передайте аудио/видеофайл в multipart-поле file или публичный URL в JSON. Операция синхронная, дедлайн — до 10 минут.

curl --fail-with-body "https://qvora.ru/api/v1/audio/transcriptions" \
  -H "Authorization: Bearer $QVORA_API_KEY" \
  -F "file=@recording.mp3" \
  -F "model=whisper-1" \
  -F "language=ru" \
  -F "response_format=verbose_json"

Модели: whisper-1, whisper-large-v3. Форматы: json — текст и стоимость, verbose_json — также длительность, язык и сегменты, text — обычный текст. Размер файла — до 200 МБ. Стоимость возвращается в заголовке x-qvora-cost-rub; длительность округляется вверх до целой минуты.

Подключение

SDK, IDE и автоматизации#

Codex CLI

Задайте QVORA_API_KEY в окружении и добавьте настройки в пользовательский ~/.codex/config.toml. Если эти параметры уже есть, обновите их значения.

# ~/.codex/config.toml
model = "gpt-5-mini"
model_provider = "qvora"
web_search = "disabled"

[model_providers.qvora]
name = "QVORA"
base_url = "https://qvora.ru/api/v1"
env_key = "QVORA_API_KEY"
wire_api = "responses"

Встроенный веб-поиск через QVORA недоступен. Справочник конфигурации Codex ↗

Claude Code

export ANTHROPIC_BASE_URL="https://qvora.ru/api"
export ANTHROPIC_AUTH_TOKEN="$QVORA_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet"
claude

Cursor, Continue и Cline

В настройках клиента выберите подключение к OpenAI-совместимому API: Base URL https://qvora.ru/api/v1, ключ QVORA и ID модели из каталога. Если клиент запрашивает полный URL метода, используйте https://qvora.ru/api/v1/chat/completions. Доступность переопределения URL и отдельных функций зависит от версии и тарифа клиента; серверные функции OpenAI и Anthropic автоматически не появляются.

n8n и Make через HTTP-запрос

Настройте HTTP Request / Make a request: метод POST, URL https://qvora.ru/api/v1/chat/completions, JSON-тело из быстрого старта. В заголовках — Authorization: Bearer … и Content-Type: application/json. Храните ключ в credentials / секретах платформы.

Извлекайте текст по пути choices[0].message.content. Для медиа сохраните id из POST /media/tasks, затем используйте ожидание с опросом или входящий вебхук. При повторах одной операции сохраняйте её ключ идемпотентности.

Пакеты и базовые вызовы SDK: документация OpenAI ↗. Поддерживаемые возможности QVORA перечислены на этой странице.

Стоимость, баланс и кэш#

Деньги во внешнем API выражены в рублях. Текст тарифицируется по фактическим токенам; перед запросом резервируется сумма, а после завершения разница возвращается. Цена зависит от прайс-бука вашего контракта.

curl --fail-with-body "https://qvora.ru/api/v1/balance" \
  -H "Authorization: Bearer $QVORA_API_KEY"

Стоимость одного запроса

qvora.cost_rub — списанная сумма, qvora.served_model — публичный ID модели, qvora.request_ref — ID для сопоставления с журналом. В потоковом Chat Completions блок приходит вместе с итоговым usage, если включён include_usage.

Ставки текста находятся в GET /models → data[].qvora.price_rub_per_1k: input, cached_input, cache_write, output. Кэш провайдера применяется при наличии совпадающего входа; попадание в кэш не гарантируется. Учтённые токены видны в usage, экономия — в qvora.cache_saved_rub.

Для медиа проверяйте правило schemas[operation].price до запуска, а после — cost.charged_rub и cost.refunded_rub. У некоторых операций цена зависит от параметров или длительности входного файла. При 402 insufficient_balance ответ содержит требуемую и доступную суммы.

Лимиты, идемпотентность и повторы#

Защита от повторного списания

Выдавайте новый ключ каждой новой операции и сохраняйте его при повторе после сетевого сбоя. Подтверждение повтора — Idempotent-Replayed: true. То же значение с другим телом: 409 idempotency_key_reused; ещё выполняющийся текстовый запрос: 409 idempotency_in_flight.

curl --fail-with-body "https://qvora.ru/api/v1/chat/completions" \
  -H "Authorization: Bearer $QVORA_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": "Ответь одним словом: привет!"
    }
  ],
  "max_completion_tokens": 1024
}'

Расходы и управление организацией#

Сводка включает API-расходы организации. group_by: day, model, key, group, member, api, end_user. Фильтры: key_id, model, api, end_user.

curl --fail-with-body "https://qvora.ru/api/v1/usage?from=2026-09-01&to=2026-09-30&group_by=day" \
  -H "Authorization: Bearer $QVORA_API_KEY"

Даты from и to задаются в формате YYYY-MM-DD по Москве; to включительно. Используйте диапазон с to позже from, не более 400 дней. По умолчанию API берёт последние примерно 30 дней.

curl --fail-with-body "https://qvora.ru/api/v1/usage/requests?limit=100&api=chat" \
  -H "Authorization: Bearer $QVORA_API_KEY"

Ответ: data[] и has_more. Для следующей страницы передайте before — Unix-время в секундах из created_at последней строки. limit — от 1 до 1 000, по умолчанию 100.

Создание ключа с лимитами

Нужен скоуп admin. Новый ключ не может получить скоупы шире ключа, который его создаёт: для примера ниже у ключа администратора должны быть admin, chat и usage.

curl --fail-with-body "https://qvora.ru/api/v1/admin/keys" \
  -H "Authorization: Bearer $QVORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Интеграция CRM",
  "scopes": [
    "chat",
    "usage"
  ],
  "monthly_limit_rub": 5000,
  "daily_limit_rub": 500,
  "rpm": 60,
  "concurrency": 5
}'

В ответе 201 сохраните key и webhook_secret: повторно они не показываются. Настройки меняются через PATCH /admin/keys/{id}, ротация — POST /admin/keys/{id}/rotate, отзыв — DELETE /admin/keys/{id}.

Группы, сотрудники, аудит и журнал вебхуков описаны в справочнике методов. Admin API не меняет владельца организации, прайс-бук или кредитный лимит.

Ошибки и диагностика#

Проверяйте HTTP-статус и машиночитаемый error.code. Для поддержки сохраните trace_id из тела и заголовок x-request-id.

{
  "error": {
    "message": "Неверный или отозванный API-ключ",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null,
    "trace_id": "req_example"
  }
}

У Messages формат Anthropic: {type: "error", error: {type, message, code}, request_id}. У медиа-задачи, принятой с 202, ошибка генерации приходит позже в поле error объекта задачи или в вебхуке.

Полный контракт

Справочник методов API#

Методов в справочнике: 35. Для каждого приведены параметры и схемы ответов. Пути указаны относительно https://qvora.ru/api/v1. Для каждого метода нужен ключ организации; дополнительные права указаны рядом с путём.

OpenAPI 3.1 · версия описания 2.0.0. Открыть JSON-схему ↗

Версии и миграция#

Сентябрь 2026 · описание API 2.0. Chat Completions с инструментами и JSON Schema, Responses и Messages, эмбеддинги, медиа-задачи и вебхуки, транскрибация, управление ключами и расходы.

Версия описания 2.0 не меняет префикс URL: используйте https://qvora.ru/api/v1. Старые пути /api/v1/ext/* сохраняются для существующих интеграций. Вместо удалённого qvora.channel используйте qvora.served_model.

Документация сверена с контрактом API 20 сентября 2026 года. Поля и методы справочника проверяются вместе со схемой при обновлении API.