Обзор моделей

Используйте страницу «Модели» или API моделей для просмотра доступных текстовых моделей. Метаданные модели включают производителя, обслуживающего провайдера, модальность, длину контекста, поддерживаемые семейства API, поддерживаемые возможности, доступность, ограничения на уровне аккаунта и цены в кредитах.

Конечная точка: GET /v1/models Назначение: Список моделей, доступных текущему аккаунту.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Матрица возможностей

Матрица совместимости семейств API

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

Каждый API-запрос использует bearer-токен. Храните ключи в серверных переменных окружения, ротируйте их при изменении доступа команды и записывайте идентификаторы запросов для отладки.

Рекомендации по безопасности ключей

1. Храните API-ключи на сервере. Не раскрывайте ключи в браузерном или мобильном клиентском коде.
2. Используйте отдельные ключи для разработки, staging-окружения, продакшена и сторонних интеграций.
3. Ограничивайте область действия ключей по окружению, сервису, клиенту или тенанту при наличии.
4. Ротируйте ключи после ухода сотрудников, изменения доступа подрядчиков или при подозрении на утечку.
5. Храните ключи в менеджерах секретов или переменных окружения, а не в исходном коде.

Кодинг-агенты

BasicRouter работает с кодинг-агентами и инструментами AI-разработки, которые поддерживают OpenAI-совместимые или Anthropic-совместимые конечные точки API. Используйте псевдонимы маршрутизации, такие как mwf/coding-auto, чтобы BasicRouter мог маршрутизировать запросы к лучшей доступной кодинг-модели без необходимости разработчикам менять конфигурацию инструмента.

Универсальная настройка, совместимая с OpenAI

Используйте эту настройку для Cursor, Codex, Hermes, OpenClaw, Continue, Aider, Cline, агентов на базе LangChain, агентов на базе LlamaIndex и пользовательских OpenAI-совместимых сред выполнения агентов.

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

Универсальная настройка, совместимая с Anthropic

Используйте эту настройку для клиентов, совместимых с Claude, и инструментов, ожидающих формат Anthropic Messages.

export ANTHROPIC_BASE_URL="https://api.basicrouter.ai/api/anthropic"
export ANTHROPIC_API_KEY="$BASICROUTER_API_KEY"
export ANTHROPIC_MODEL="mwf/coding-auto"

Рекомендуемые модели для агентов

Краткое руководство по Cursor

Используйте конечную точку, совместимую с OpenAI.

Base URL: https://api.basicrouter.ai/api/v1
API Key:  BASICROUTER_API_KEY
Model:    mwf/coding-auto

Рекомендуемые шаги:

1. Откройте настройки Cursor.
2. Добавьте или включите конфигурацию OpenAI-совместимого API-ключа.
3. Установите переопределение базового URL OpenAI на https://api.basicrouter.ai/api/v1.
4. Добавьте пользовательскую модель, например mwf/coding-auto, mwf/coding-fast или mwf/coding-long.
5. Используйте модель с поддержкой потоковой передачи и вызова инструментов для наилучшего поведения агента.

Устранение неполадок:

Краткое руководство по Claude Code

Используйте Anthropic-совместимую конечную точку шлюза.

export ANTHROPIC_BASE_URL="https://api.basicrouter.ai/api/anthropic"
export ANTHROPIC_API_KEY="$BASICROUTER_API_KEY"
export ANTHROPIC_MODEL="mwf/coding-auto"

BasicRouter поддерживает этот Anthropic-совместимый путь для совместимости с Claude Code и Anthropic SDK:

POST /api/v1/messages

Рекомендуемые требования:

Краткое руководство по Codex

Используйте BasicRouter как пользовательского OpenAI-совместимого провайдера моделей.

Пример конфигурации провайдера:

[model_providers.basicrouter]
name = "BasicRouter"
base_url = "https://api.basicrouter.ai/api/v1"
env_key = "BASICROUTER_API_KEY"
wire_api = "responses"

model_provider = "basicrouter"
model = "mwf/coding-auto"

Переменная окружения:

export BASICROUTER_API_KEY="br_xxx"

Рекомендуемые модели:

Устранение неполадок:

Краткое руководство по Hermes

Используйте OpenAI-совместимую конечную точку, если только ваше развертывание Hermes не настроено для другого протокола.

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

Рекомендуемая политика моделей:

Краткое руководство по OpenClaw

Используйте OpenAI-совместимую конечную точку для конфигурации среды выполнения агента в стиле OpenAI.

export OPENAI_BASE_URL="https://api.basicrouter.ai/api/v1"
export OPENAI_API_KEY="$BASICROUTER_API_KEY"
export OPENAI_MODEL="mwf/coding-auto"

Если OpenClaw поддерживает нескольких провайдеров, настройте BasicRouter как OpenAI-совместимого провайдера и используйте псевдонимы маршрутизации BasicRouter для выбора модели.

{
  "provider": "openai-compatible",
  "base_url": "https://api.basicrouter.ai/api/v1",
  "api_key_env": "BASICROUTER_API_KEY",
  "model": "mwf/coding-auto"
}

Контрольный список совместимости агента

Использование консоли

Консоль BasicRouter — это операционная плоскость управления для доступа к API, доступности моделей, политик маршрутизации, мониторинга использования и администрирования биллинга. Она предоставляет администраторам аккаунта централизованное представление ключей, моделей, запросов, кредитов и средств управления на уровне аккаунта для продакшен-трафика моделей.

Управление ключами API

Создавайте, ротируйте, отзывайте и помечайте API-ключи из консоли. Используйте отдельные ключи для разработки, staging-окружения, продакшена и отдельных сервисов, чтобы использование можно было аудировать и изолировать по окружению или приложению.

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

Используйте страницу «Модели» для просмотра моделей, доступных аккаунту. Каждая запись о модели может включать вендора, обслуживающего провайдера, модальность, поддерживаемые семейства API, длину контекста, флаги возможностей, статус доступности и информацию о ценах.

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

Использование и журналы

Представление «Использование и журналы» обеспечивает оперативную видимость API-трафика. Команды могут проверять объём запросов, выбранные модели, разрешённые цели маршрутизации, потребление кредитов, задержку, коды ошибок и идентификаторы запросов.

• Устранение неполадок неудачных запросов.
• Выявление дорогостоящих рабочих нагрузок.
• Сравнение использования моделей между приложениями и окружениями.
• Проверка поведения маршрутизации и резерва.
• Исследование проблем задержки или доступности провайдера.
• Предоставление идентификаторов запросов при обращении в поддержку.

Каждый ответ API включает или раскрывает идентификатор запроса BasicRouter. Сохраняйте этот идентификатор в журналах вашего приложения для повышения эффективности отладки в продакшене и эскалации поддержки.

Резерв

Резерв (fallback) — это механизм отказоустойчивости BasicRouter. Когда основная модель или политика маршрутизации даёт сбой, система автоматически переключается на резервную модель, чтобы продолжить обработку запроса. Это сохраняет отзывчивость приложения и минимизирует риск нарушения работы сервиса.

Почему важен резерв

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

• Сбой сервиса модели: вышестоящий API временно недоступен или превышает время ожидания.
• Колебания производительности: высокая нагрузка на модель приводит к медленным или неудачным ответам.
• Сбой маршрутизации: все модели-кандидаты, выбранные умной маршрутизацией, становятся недоступными.

Резерв поддерживает доступность вашего приложения, предоставляя надёжный резервный путь.

Ключевые преимущества

Глобальная конфигурация резервной модели

BasicRouter поддерживает настройку глобальной резервной модели из бэкенда консоли. Все запросы автоматически используют эту модель в качестве резерва при сбое.

Как настроить:

1. Перейдите на страницу настроек стратегии BasicRouter.
2. Найдите настройку Модель резерва по умолчанию.
3. Выберите вашу глобальную резервную модель из выпадающего списка.
4. Сохраните настройку, чтобы применить её немедленно.

Преимущества глобальной конфигурации:

• Изменения кода не требуются: настройте один раз, и это применяется глобально, без необходимости повторять настройку в каждом запросе.
• Централизованное управление: управляйте политикой резерва в одном месте для более удобной корректировки и мониторинга.
• Упрощённое обслуживание: снижает сложность кода и вероятность ошибок конфигурации.
• Гибкое переопределение: конфигурация резерва на уровне запроса имеет приоритет и может переопределять глобальную настройку для конкретных сценариев.

Конфигурация резерва на уровне запроса

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

Укажите резервную модель с помощью параметра router.fallBackModels:

{
  "model": "claude-sonnet-4",
  "messages": [
    {
      "role": "user",
      "content": "Explain what quantum computing is"
    }
  ],
  "router": {
    "fallBackModels": ["glm-5.2"]
  }
}

Правила приоритета

При наличии нескольких конфигураций резерва приоритет распределяется от высшего к низшему:

1. router.fallBackModels на уровне запроса: резервная модель, указанная в отдельном запросе.
2. Глобальная модель резерва по умолчанию: глобальная резервная модель, настроенная в консоли.
3. Без резерва: если ни одна из них не настроена, запрос возвращает ошибку при сбое.

Администрирование аккаунта

В зависимости от типа аккаунта консоль может включать включение моделей на уровне аккаунта, элементы управления реселлером или дистрибьютором, конфигурацию биллинга и настройки доступа. Администраторы могут использовать эти элементы управления для согласования доступа к моделям, видимости использования и ответственности за биллинг с приложениями, клиентскими аккаунтами или бизнес-подразделениями.

Контрольный список производственных операций

Биллинг и кредиты

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

Подробная информация о ценах на модели доступна на странице «Модели» или через API метаданных моделей. Цены могут различаться в зависимости от модели, провайдера, модальности, разрешения, типа токенов, длины вывода, длительности задачи, типа аккаунта и коммерческого соглашения.

Пополнение и кошелёк

Аккаунты могут добавлять кредиты на кошелёк с оплатой по факту использования для гибкого использования. Кредиты кошелька используются после того, как кредиты месячного тарифа и пакеты ресурсов будут израсходованы, если к аккаунту не применяется пользовательское правило биллинга.

Кредиты кошелька не истекают, если иное не указано в применимых коммерческих условиях. При пополнении кошелька с оплатой по факту использования взимается сервисный сбор.

Месячные тарифы и пакеты ресурсов

Каждый пользователь или аккаунт может выбрать один активный месячный тариф. Месячные тарифы предоставляют определённый объём пропускной способности использования, коммерческие условия и конфигурацию доступа на уровне аккаунта для расчётного периода.

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

Порядок списания

Если не настроены пользовательские правила биллинга, кредиты списываются в следующем порядке:

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

Индивидуальное ценообразование

Ценообразование может быть настроено для каждого пользователя или аккаунта. Корпоративные клиенты, аккаунты реселлеров, аккаунты дистрибьюторов и клиенты с большим объёмом использования могут иметь право на индивидуальное ценообразование. Свяжитесь с отделом продаж для получения предложения.

Индивидуальное ценообразование может быть настроено по аккаунту, модели, провайдеру, модальности, региону, объёму использования или коммерческому соглашению. Когда включено индивидуальное ценообразование, консоль и API биллинга отражают специфичные для аккаунта цены и правила списания там, где это доступно.

Единицы ценообразования

Разные модальности моделей используют разные единицы измерения. BasicRouter конвертирует эти единицы в кредиты в соответствии с правилами ценообразования модели.

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

Атрибуция использования

Использованием BasicRouter можно просматривать по аккаунту, API-ключу, модели, модальности или диапазону времени. Это позволяет командам относить затраты к приложениям, окружениям, клиентам или внутренним бизнес-подразделениям.

Баланс кредитов

Проверьте, сколько кредитов доступно на вашем аккаунте. Баланс разделён на три кошелька, которые списываются по порядку: месячный лимит тарифа, приобретённые пакеты ресурсов и кошелёк с оплатой по факту. Также доступен общий ресурсный итог (месячный тариф + пакеты ресурсов, без учёта оплаты по факту) для отслеживания включённого использования отдельно от расходов на пополнение.

Чтобы получить эти данные программно, см. GET /v1/billing/balance в Справочнике API.

Сведения об использовании

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

Чтобы получить эти данные программно, см. GET /v1/usage в Справочнике API.

История транзакций

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

Чтобы получить эти данные программно, см. GET /v1/billing/transactions в Справочнике API.

Неудачные запросы и возвраты

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

Для асинхронных задач генерации изображений и видео поведение биллинга зависит от того, была ли задача принята, начата, завершена, выполнена с ошибкой или отменена. Ответ с деталями задачи включает информацию об использовании, когда кредиты были потреблены.

Пополнения, месячные тарифы, пакеты ресурсов и потреблённые кредиты возврату не подлежат, если иное не предусмотрено применимым коммерческим соглашением или не требуется по закону.

Справочник API

Общие соглашения

Базовый URL

Все конечные точки обслуживаются с префиксом /v1.

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

Вызовы к конечным точкам /v1/* используют аутентификацию API Key (не JWT). API-ключ передаётся через следующий заголовок:

Отсутствующие или недействительные ключи возвращают 401.

Предварительная проверка баланса

Все конечные точки вызова моделей выполняют предварительную проверку баланса перед выполнением:

• Недостаточный баланс возвращает Insufficient credit, что соответствует:
  • Протокол OpenAI: HTTP 400, code = insufficient_quota
  • Протокол Anthropic: HTTP 402, type = billing_error
• Некоторые конечные точки также оценивают минимальную стоимость по модели для второй предварительной проверки.

POST https://api.basicrouter.ai/api/v1/chat/completions

Конечная точка, совместимая с OpenAI Chat Completions. Поддерживает потоковый и непотоковый режимы, вызовы инструментов, режим JSON и мультимодальный ввод.

Поля Message:

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/chat/completions \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "glm-5.2",
    "messages": [{"role": "user", "content": "Describe Hangzhou in one sentence."}],
    "stream": false,
    "temperature": 0.7
  }'

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1721380000,
  "model": "glm-5.2",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hangzhou is ..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 12, "completion_tokens": 18, "total_tokens": 30}
}

Поля ответа (непотоковый):

Пример потокового ответа:

data: {"object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant","content":"..."}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"..."}}]}

data: [DONE]

POST https://api.basicrouter.ai/api/v1/responses

Конечная точка, совместимая с OpenAI Responses. Использует input вместо messages, instructions вместо системного сообщения и блок text вместо response_format.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/responses \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "glm-5.2",
    "input": "Describe Hangzhou in one sentence.",
    "instructions": "Be concise.",
    "stream": false
  }'

{
  "id": "resp_xxx",
  "object": "response",
  "model": "glm-5.2",
  "status": "completed",
  "created_at": 1721380000,
  "output": [
    {
      "id": "msg_xxx",
      "type": "message",
      "role": "assistant",
      "content": [{"type": "output_text", "text": "Hangzhou is ..."}],
      "status": "completed"
    }
  ],
  "usage": {"input_tokens": 12, "output_tokens": 18, "total_tokens": 30}
}

Поля ответа (непотоковый):

Потоковая передача следует событиям Responses API:

POST https://api.basicrouter.ai/api/v1/messages

Конечная точка, совместимая с Anthropic Messages. Принимает заголовки x-api-key и anthropic-version: 2023-06-01. Блоки содержимого поддерживают text, image, tool_use, tool_result, thinking и redacted_thinking.

Примеры блоков изображений:

{ "type": "image", "source": { "type": "base64", "media_type": "...", "data": "..." } }
{ "type": "image", "source": { "type": "url", "url": "..." } }

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/messages \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "claude-sonnet-4.6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Describe Hangzhou in one sentence."}]
  }'

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4.6",
  "content": [{"type": "text", "text": "Hangzhou is ..."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 12, "output_tokens": 18}
}

Поля ответа (непотоковый):

GET https://api.basicrouter.ai/api/v1/models

Возвращает все онлайн-модели API, которые включены.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "glm-5.2",
      "object": "model",
      "display_name": "glm-5.2",
      "created": 1721380000,
      "owned_by": "Zai",
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "context_length": 128000
    }
  ]
}

Поля каждой записи модели (data[]):

GET https://api.basicrouter.ai/api/v1/models/{model}

Возвращает одну модель с той же структурой, что и элемент списка. Возвращает HTTP 404, если модель не существует.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/models/gpt-5.5 \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Ответ при успешном выполнении: один объект модели с теми же полями, что и элемент списка /v1/models.

Если модель не существует, возвращается HTTP 404:

{"error": {"message": "The model 'xxx' does not exist", "type": "invalid_request_error", "code": "invalid_model_error"}}

GET https://api.basicrouter.ai/api/v1/image-models

Запросите поддерживаемые разрешением, соотношения сторон и максимальные количества для модели генерации изображений перед вызовом /v1/image-generations. Аутентификация не требуется.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/image-models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "image_model",
      "displayName": "GPT Image 1",
      "description": "...",
      "icon": "...",
      "created": 1721380000,
      "maxCount": 4,
      "fileMax": 10,
      "resolutions": ["720p", "1080p"],
      "ratios": ["1:1", "3:2"]
    }
  ]
}

GET https://api.basicrouter.ai/api/v1/video-models

Запросите поддерживаемые значения videoType, диапазон длительности, разрешения и соотношения сторон для видеомодели перед вызовом /v1/video-generations. Аутентификация не требуется.

Поля VideoTypeOption:

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/video-models \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "sora-2",
      "object": "video_model",
      "displayName": "Sora 2",
      "description": "...",
      "icon": "...",
      "created": 1721380000,
      "allowedVideoTypes": [
        {"code": 1, "name": "text-to-video"},
        {"code": 2, "name": "image-to-video"},
        {"code": 3, "name": "image-to-video (first/last frame)"}
      ],
      "videoDurationMin": 5,
      "videoDurationMax": 10,
      "videoDurationSuggest": [5, 8, 10],
      "resolutions": ["1080p", "720p"],
      "ratios": ["16:9", "9:16"],
      "fileMax": 5
    }
  ]
}

POST https://api.basicrouter.ai/api/v1/image-generations

Асинхронно отправьте задачу генерации изображений. Немедленно возвращает taskId; получите результат опросом GET /v1/image-generations/{taskId} или через вебхук callbackUrl.

Значения model, поддерживаемые значения resolution / ratio, верхний предел count и лимит загрузки референсных изображений (fileMax) необходимо сначала получить из GET /v1/image-models. Принимаются только значения, заявленные в спецификации модели.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/image-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-4.5",
    "text": "A cat drinking water by the river",
    "count": 1,
    "resolution": "2k",
    "ratio": "1:1",
    "imageUrls": []
  }'

{
  "code": 200,
  "message": "image task is commit",
  "data": {"taskId": "img_xxx"}
}

Ответы при ошибках:

// Insufficient credit
{ "code": 500, "message": "Insufficient credit" }

// Model not found
{ "code": 404, "message": "Model not found: xxx" }

GET https://api.basicrouter.ai/api/v1/image-generations/{taskId}

Опрос задачи генерации изображений. status имеет значение pending / success / failed. images — это JSON-строка массива URL изображений; text содержит любое текстовое описание, добавленное моделью (например, мультимодальный вывод Gemini), иначе null.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/image-generations/img_xxx \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "img_xxx",
    "status": "success",
    "errorMessage": null,
    "images": "[\"https://.../1.png\"]",
    "text": null
  }
}

Поля data ответа:

Задача не найдена:

{ "code": 500, "message": "task not found" }

Если при отправке был предоставлен callbackUrl, сервер отправляет окончательный результат success / failed через вебхук с той же структурой data.

Полный пример (отправка + опрос)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ImageGenerationExample {
  private static final String BASE = "https://api.basicrouter.ai/api/v1";
  private static final String API_KEY = System.getenv("BASICROUTER_API_KEY");

  public static void main(String[] args) throws Exception {
    HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10)).build();

    // 1. Submit the task.
    String body = "{"
        + "\"model\":\"seedream-4.5\","
        + "\"text\":\"A cat drinking water by the river\","
        + "\"count\":1,"
        + "\"resolution\":\"2k\","
        + "\"ratio\":\"1:1\","
        + "\"imageUrls\":[]"
        + "}";
    HttpResponse<String> submit = http.send(
        HttpRequest.newBuilder(URI.create(BASE + "/image-generations"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
        HttpResponse.BodyHandlers.ofString());

    String taskId = extract(submit.body(), "taskId");
    System.out.println("taskId = " + taskId);

    // 2. Poll until terminal status.
    String status = "pending";
    while ("pending".equals(status)) {
      Thread.sleep(15_000L);
      HttpResponse<String> poll = http.send(
          HttpRequest.newBuilder(URI.create(BASE + "/image-generations/" + taskId))
              .header("Authorization", "Bearer " + API_KEY).GET().build(),
          HttpResponse.BodyHandlers.ofString());
      status = extract(poll.body(), "status");
      System.out.println("status = " + status);
    }

    if (!"success".equals(status)) {
      throw new RuntimeException("image generation failed: " + status);
    }
    // images is a JSON-stringified array of URLs.
    String images = extract(pollResult(http, taskId), "images");
    System.out.println("images = " + images);
  }

  // Minimal JSON field extractor — use Jackson/Gson in production.
  private static String extract(String json, String field) {
    int i = json.indexOf("\"" + field + "\":");
    if (i < 0) return null;
    i += field.length() + 3;
    if (json.charAt(i) == '\"') {
      int end = json.indexOf('\"', i + 1);
      return json.substring(i + 1, end);
    }
    int end = i;
    while (end < json.length() && "0123456789.".indexOf(json.charAt(end)) >= 0) end++;
    return json.substring(i, end);
  }

  private static String pollResult(HttpClient http, String taskId) throws Exception {
    return http.send(HttpRequest.newBuilder(URI.create(BASE + "/image-generations/" + taskId))
        .header("Authorization", "Bearer " + API_KEY).GET().build(),
        HttpResponse.BodyHandlers.ofString()).body();
  }
}

import os
import time
import requests

BASE = "https://api.basicrouter.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BASICROUTER_API_KEY']}"}

# 1. Submit the task.
resp = requests.post(
    f"{BASE}/image-generations",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "model": "seedream-4.5",
        "text": "A cat drinking water by the river",
        "count": 1,
        "resolution": "2k",
        "ratio": "1:1",
        "imageUrls": [],
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print(f"taskId = {task_id}")

# 2. Poll until terminal status.
while True:
    time.sleep(15)
    poll = requests.get(f"{BASE}/image-generations/{task_id}", headers=HEADERS)
    poll.raise_for_status()
    data = poll.json()["data"]
    status = data["status"]
    print(f"status = {status}")
    if status != "pending":
        break

if status != "success":
    raise RuntimeError(f"image generation failed: {data.get('errorMessage')}")

# images is a JSON-stringified array of URLs.
import json
images = json.loads(data["images"])
print(f"images = {images}")

POST https://api.basicrouter.ai/api/v1/video-generations

Асинхронно отправьте задачу генерации видео. Немедленно возвращает taskId; получите результат опросом GET /v1/video-generations/{taskId} или через вебхук callbackUrl.

Значения model, разрешённые значения videoType, диапазон длительности (videoDurationMin/Max), поддерживаемые resolution / ratio и лимит загрузки референсных ресурсов (fileMax) необходимо сначала получить из GET /v1/video-models. Принимаются только коды videoType, перечисленные в allowedVideoTypes этой модели.

Примеры для каждого videoType:

1. Текст в видео (videoType=1)

Генерация видео только из текстового промпта; референсные ресурсы не требуются.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 1,
    "text": "A cat jumping on a bed",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0"
  }'

2. Изображение в видео — первый кадр (videoType=2)

Предоставьте один начальный кадр в imageUrls; модель генерирует видео, начиная с этого кадра.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 2,
    "text": "Happily shaking head",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0",
    "imageUrls": ["https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/first-frame.png"]
  }'

3. Изображение в видео — первый и последний кадр (videoType=3)

Предоставьте и первый, и последний кадр в imageUrls (порядок: [первый, последний]); модель генерирует переходное видео между двумя кадрами.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 3,
    "text": "Put on the hat",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "seedance-2.0",
    "imageUrls": [
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/first-frame.png",
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/last-frame.png"
    ]
  }'

4. Изображение в видео — референс (videoType=4)

Предоставьте одно или несколько референсных изображений в imageUrls; модель использует их стиль/содержимое как референс (не как обязательный первый/последний кадр) для генерации видео.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 4,
    "text": "Two cats playing together",
    "resolution": "480p",
    "ratio": "16:9",
    "duration": 4,
    "model": "kling-v3-omni-video",
    "imageUrls": [
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/ref-1.png",
      "https://basicrouter-flie.oss-accelerate.aliyuncs.com/test/ref-2.png"
    ]
  }'

5. Все референсы (videoType=5)

Смешанные референсы изображений / видео / аудио. Указывайте референсные ресурсы по позиции в промпте: 1-й элемент в imageUrls — это @图片 1, 1-й в videoUrls — @视频 1, 1-й в audioUrls — @音频 1. videoUrls также принимает простые строки URL.

curl --request POST \
  --url https://api.basicrouter.ai/api/v1/video-generations \
  --header "Authorization: Bearer $BASICROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "videoType": 5,
    "text": "Use the first-person framing of @视频 1 and @音频 1 as background music. First-person tea ad; start frame is @图片 1 ... end frame is @图片 2.",
    "model": "seedance-2.0",
    "imageUrls": [
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg",
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
    ],
    "videoUrls": ["https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"],
    "audioUrls": ["https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 11
  }'

Ответ при отправке (для всех пяти типов):

{
  "code": 200,
  "message": "success",
  "data": {"taskId": "vid_xxx"}
}

GET https://api.basicrouter.ai/api/v1/video-generations/{taskId}

Опрос задачи генерации видео. status имеет значение pending / success / failed; videoUrl — URL сгенерированного видео, а lastFrameUrl — URL последнего кадра (для сценариев image-to-video).

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/video-generations/vid_xxx \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "status": "success",
    "videoUrl": "https://.../out.mp4",
    "lastFrameUrl": null,
    "message": null
  }
}

Поля data ответа:

Если при отправке был предоставлен callbackUrl, сервер отправляет окончательный результат через вебхук с той же структурой data.

Полный пример (отправка + опрос)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class VideoGenerationExample {
  private static final String BASE = "https://api.basicrouter.ai/api/v1";
  private static final String API_KEY = System.getenv("BASICROUTER_API_KEY");

  public static void main(String[] args) throws Exception {
    HttpClient http = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10)).build();

    // 1. Submit the task (videoType=1: text-to-video).
    String body = "{"
        + "\"videoType\":1,"
        + "\"text\":\"A cat jumping on a bed\","
        + "\"resolution\":\"480p\","
        + "\"ratio\":\"16:9\","
        + "\"duration\":4,"
        + "\"model\":\"seedance-2.0\""
        + "}";
    HttpResponse<String> submit = http.send(
        HttpRequest.newBuilder(URI.create(BASE + "/video-generations"))
            .header("Authorization", "Bearer " + API_KEY)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
        HttpResponse.BodyHandlers.ofString());

    String taskId = extract(submit.body(), "taskId");
    System.out.println("taskId = " + taskId);

    // 2. Poll until terminal status. Video tasks take longer — poll every 20s.
    String status = "pending";
    String lastBody = null;
    while ("pending".equals(status)) {
      Thread.sleep(20_000L);
      HttpResponse<String> poll = http.send(
          HttpRequest.newBuilder(URI.create(BASE + "/video-generations/" + taskId))
              .header("Authorization", "Bearer " + API_KEY).GET().build(),
          HttpResponse.BodyHandlers.ofString());
      lastBody = poll.body();
      status = extract(lastBody, "status");
      System.out.println("status = " + status);
    }

    if (!"success".equals(status)) {
      throw new RuntimeException("video generation failed: " + status);
    }
    String videoUrl = extract(lastBody, "videoUrl");
    System.out.println("videoUrl = " + videoUrl);
  }

  // Minimal JSON field extractor — use Jackson/Gson in production.
  private static String extract(String json, String field) {
    int i = json.indexOf("\"" + field + "\":");
    if (i < 0) return null;
    i += field.length() + 3;
    if (json.charAt(i) == '\"') {
      int end = json.indexOf('\"', i + 1);
      return json.substring(i + 1, end);
    }
    int end = i;
    while (end < json.length() && "0123456789.".indexOf(json.charAt(end)) >= 0) end++;
    return json.substring(i, end);
  }
}

import os
import time
import requests

BASE = "https://api.basicrouter.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BASICROUTER_API_KEY']}"}

# 1. Submit the task (videoType=1: text-to-video).
resp = requests.post(
    f"{BASE}/video-generations",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "videoType": 1,
        "text": "A cat jumping on a bed",
        "resolution": "480p",
        "ratio": "16:9",
        "duration": 4,
        "model": "seedance-2.0",
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print(f"taskId = {task_id}")

# 2. Poll until terminal status. Video tasks take longer — poll every 20s.
while True:
    time.sleep(20)
    poll = requests.get(f"{BASE}/video-generations/{task_id}", headers=HEADERS)
    poll.raise_for_status()
    data = poll.json()["data"]
    status = data["status"]
    print(f"status = {status}")
    if status != "pending":
        break

if status != "success":
    raise RuntimeError(f"video generation failed: {data.get('message')}")

print(f"videoUrl = {data['videoUrl']}")
if data.get("lastFrameUrl"):
    print(f"lastFrameUrl = {data['lastFrameUrl']}")

GET https://api.basicrouter.ai/api/v1/billing/balance

Возвращает баланс аккаунта, разделённый на три кошелька: месячный тариф, пакеты ресурсов и кредиты с оплатой по факту.

curl --request GET \
  --url https://api.basicrouter.ai/api/v1/billing/balance \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

{
  "totalCredit": 128.50,
  "totalResourceCredit": 30.00,
  "wallets": {
    "monthlyPlan": {"id": "pkg_xxx", "credit": 50.00, "name": "Monthly plan"},
    "resourcePacks": [
      {"id": "rp_xxx", "credit": 30.00, "name": "Video resource pack"}
    ],
    "payAsYouGo": 48.50
  }
}

Поля ответа:

Поля WalletDetailVO::

GET https://api.basicrouter.ai/api/v1/usage

Постраничные детали биллинга вызовов моделей, снимок по цене (priceSnapshotId), упорядоченные по времени создания заказа в порядке убывания. Возвращаются только обычные записи списания (reason = model usage).

Параметры запроса:

curl --request GET \
  --url "https://api.basicrouter.ai/api/v1/usage?page=1&size=20&startTime=2026-07-01T00:00:00&endTime=2026-07-31T23:59:59" \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Обёртка ответа:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

Поля UsageDetailVO:

Поля CreditDetailItem:

Соглашение о null-значениях: заполняются только поля, относящиеся к каждому modelType; остальные равны null. Для text заполняются поля токенов; для image — imageCount/imageResolution/imageRatio; для video — videoResolution/videoRatio/videoDurationSec.

Пример ответа:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "priceSnapshotId": "snap_9f3c1a2b",
        "taskId": "task_5e8a1c33",
        "credit": 0.0342,
        "model": "glm-5.2",
        "modelType": "text",
        "inputTokens": 1280,
        "outputTokens": 642,
        "totalTokens": 1922,
        "cacheReadTokens": 0,
        "cacheWriteTokens": 0,
        "imageCount": null,
        "imageResolution": null,
        "imageRatio": null,
        "videoResolution": null,
        "videoRatio": null,
        "videoDurationSec": null,
        "orderCreatedAt": "2026-07-18T14:23:11",
        "creditDetails": [
          {
            "credit": 0.0342,
            "deductionSource": "balance",
            "packageName": ""
          }
        ]
      },
      {
        "priceSnapshotId": "snap_a12f77c0",
        "taskId": "task_c71e44a2",
        "credit": 1.8000,
        "model": "seedance-2.0",
        "modelType": "video",
        "inputTokens": null,
        "outputTokens": null,
        "totalTokens": null,
        "cacheReadTokens": null,
        "cacheWriteTokens": null,
        "imageCount": null,
        "imageResolution": null,
        "imageRatio": null,
        "videoResolution": "1080p",
        "videoRatio": "16:9",
        "videoDurationSec": 8,
        "orderCreatedAt": "2026-07-17T22:41:09",
        "creditDetails": [
          {
            "credit": 1.5000,
            "deductionSource": "Monthly Package",
            "packageName": "基础月度套餐"
          },
          {
            "credit": 0.3000,
            "deductionSource": "Resource Package",
            "packageName": "byteplus视频资源包"
          }
        ]
      }
    ],
    "total": 128,
    "current": 1,
    "size": 20,
    "pages": 7
  }
}

GET https://api.basicrouter.ai/api/v1/billing/transactions

Постраничный список оплаченных (status=2) транзакций пополнения текущего пользователя, отсортированных по created_at по убыванию.

curl --request GET \
  --url "https://api.basicrouter.ai/api/v1/billing/transactions?page=1&size=20&startTime=2026-07-01%2000:00:00&endTime=2026-07-31%2023:59:59" \
  --header "Authorization: Bearer $BASICROUTER_API_KEY"

Обёртка ответа:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

Поля TransactionVO:

Поля TransactionVO:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "orderNo": "R20260718abc123",
        "thirdPartyOrderNo": "wx_pay_xxx",
        "amount": 50.00,
        "actualAmount": 48.50,
        "discount": 1.50,
        "paymentMethod": "wechat",
        "serviceFeeAmount": 0.00,
        "paymentChannel": "wechat",
        "source": "recharge",
        "packageName": null,
        "createdAt": "2026-07-18T14:23:11"
      }
    ],
    "total": 28,
    "current": 1,
    "size": 20,
    "pages": 2
  }
}

Эксплуатация

Ошибки

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

Совместимые с провайдерами конечные точки по возможности сохраняют форму ошибок исходного семейства API. Собственные конечные точки BasicRouter используют объект ошибок BasicRouter.

Соответствие HTTP-статусов и кодов ошибок

Частые коды ошибок