Документация

Адрес и ключ

API совместим с OpenAI Chat Completions: подходят OpenAI SDK и любые программы, в которых можно указать адрес OpenAI-совместимого API.

Base URL

https://artaill.ru/api/gateway/v1

Авторизация

Authorization: Bearer … с API-ключом

API-ключ создаётся в кабинете: для него выбирают доступные модели и месячный бюджет. Ключ показывается один раз — сохраните его. Запросы оплачиваются с баланса аккаунта в пределах бюджета ключа.

Пути указаны относительно Base URL.

POST /chat/completions

Ответ модели целиком (JSON) или потоком (SSE).

GET /models

Модели, доступные ключу; GET /models/{id} — одна модель.

Цены — на странице моделей. Каталог в JSON с ролями сообщений и параметрами каждой модели — /api/gateway/catalog, ключ для него не нужен.

Первый запрос

Выберите модель, разрешённую вашему ключу.

Текст ответа — в choices[0].message.content, число токенов — в usage. Стоимость запроса видна в журнале запросов.

{
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Привет! Чем помочь?"},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}

Справочники SDK: Python и JavaScript / TypeScript.

Параметры

Историю диалога хранит и передаёт ваше приложение. Artaill не сохраняет тексты запросов и ответов; правила обработки у поставщика модели могут отличаться — подробнее в политике конфиденциальности.

model

Обязательный. ID модели из каталога.

messages

Обязательный. Массив сообщений с role и content; допустимые роли зависят от модели.

max_tokens или max_completion_tokens

Предел вывода в токенах, от 1 до максимума модели; укажите только один из двух. По умолчанию — значение из каталога.

stream

true — ответ потоком SSE, по умолчанию false. Чтобы получить usage в потоке, добавьте stream_options: {"include_usage": true}.

У моделей с рассуждениями в предел вывода могут входить токены рассуждений: при слишком маленьком пределе ответ может остаться без текста. Вход вместе с пределом вывода должен помещаться в контекст модели.

Неизвестный или не поддерживаемый моделью параметр отклоняется с ошибкой 400 до вызова модели; такой запрос не оплачивается.

Изображения, JSON, функции

Изображения принимают не все модели — это видно в каталоге. Поддержку response_format и tools показывает JSON-каталог.

{
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Что изображено на фото?"},
      {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
    ]
  }]
}

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "summary",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {"summary": {"type": "string"}},
        "required": ["summary"],
        "additionalProperties": false
      }
    }
  }
}

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_order_status",
      "description": "Узнать статус заказа по номеру",
      "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
        "additionalProperties": false
      }
    }
  }],
  "tool_choice": "auto"
}

{"role": "tool", "tool_call_id": "ID из tool_calls", "content": "{\"status\":\"shipped\"}"}

Потоковый ответ

Пример — в первом запросе, вариант «Поток · SSE».

Успешный поток заканчивается строкой data: [DONE]. С include_usage перед ней приходит отдельное событие с choices: [] и usage — уже после finish_reason, поэтому читайте поток до конца. Если провайдер не сообщил полный отчёт о токенах, usage равен null.

Ошибка после начала потока приходит событием data: {"error": {...}}, затем соединение закрывается без [DONE]. HTTP-статус к этому моменту уже 200, поэтому успешное завершение определяет только [DONE].

Ограничения

Одновременные запросы

До 2 выполняющихся запросов на аккаунт, включая ответы в чате Artaill. Очереди нет: запрос сверх лимита получает 429.

Частота

До 60 запросов в минуту на ключ и 120 на аккаунт, считая все запросы с ключом.

Размер запроса

JSON — до 16 MiB; текст, включая описания функций и схемы, — до 1 MiB; до 512 сообщений. Контекст и предел вывода у каждой модели свои.

429 также возможен при общей нагрузке на сервис. Заголовок Retry-After, если он есть, указывает, через сколько секунд повторить запрос.

Ошибки

Ошибка до начала ответа приходит с HTTP-статусом и JSON-объектом error с полями code, type, message и param. Обрабатывайте ошибки по code: текст message может меняться.

400 / 413

Неверный или неподдерживаемый параметр, слишком большой запрос. Без исправления повтор не поможет.

401

Ключ неверен, отозван или истёк.

402

insufficient_balance — не хватает средств на балансе; key_budget_exceeded — бюджета ключа; key_reservation_exceeded — резерв больше предела ключа на один запрос. Резерв считается по входу и пределу вывода, их уменьшение его снижает.

403

model_not_allowed — модель не разрешена ключу; cross_origin_denied — запрос из браузера с другого сайта.

404

Модель или запрос не найдены.

409

request_already_accepted — запрос с этим Idempotency-Key уже принят. Ответ содержит его ID и ссылку на состояние.

429

Превышена частота или число одновременных запросов. Повторите позже, с учётом Retry-After.

5xx

Ошибка или тайм-аут модели, временная недоступность сервиса. Запрос мог дойти до модели и быть оплачен: перед повтором проверьте его состояние. accounting_pending — расчёт ещё не завершён.

Повторы и расходы

Ответ на принятый запрос содержит заголовок X-Request-ID. По этому ID состояние и стоимость запроса видны в журнале и через GET /api/gateway/requests/{id} с тем же API-ключом. Текст ответа там не хранится.

Работа модели оплачивается и при ошибке или обрыве соединения. Без заголовка Idempotency-Key каждый POST — новый вызов модели, поэтому повторы SDK в примерах отключены. После сбоя сначала проверьте состояние запроса.

Idempotency-Key защищает от повторного выполнения: передайте уникальное значение для каждой операции, от 1 до 128 печатных ASCII-символов без пробелов. Значение действует 24 часа с момента принятия запроса, даже если тот завершился ошибкой. Повтор с тем же значением и API-ключом модель не вызывает: сервис вернёт 409 с request_id и status_url в JSON и заголовком Location. Тело запроса не сравнивается, прежний ответ не возвращается.