Аутентификация и базовые соглашения

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

Базовый адрес

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

Все эндпоинты используют один и тот же платформенный API Key:

Authorization: Bearer sk-你的APIKey
Content-Type: application/json

Префикс Bearer можно опустить (но не рекомендуется)

На практике проверены четыре варианта записи:

Платформа принимает и голый token, поэтому ответ 200 не означает, что клиент настроен правильно. И наоборот: если какой-то клиент возвращает 401, сначала проверьте, не пропускает ли он весь заголовок Authorization, а не подозревайте сразу сам ключ. Всегда используйте запись с Bearer.

Если API Key отсутствует, указан неверно, отключён или принадлежит другой учётной записи, возвращается HTTP 401:

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 202609221135501066578648268d9d6uXuM5QgH)",
    "type": "new_api_error"
  }
}

Обратите внимание: code — пустая строка. При сбое аутентификации платформа не заполняет code, поэтому не определяйте по пустоте code, завершился ли запрос ошибкой — ориентируйтесь на код состояния HTTP. request id из message можно сразу извлечь для обращения в поддержку.

Такая ошибка аутентификации на всех эндпоинтах имеет одинаковую структуру, а message содержит идентификатор запроса, что упрощает диагностику.

Структура ответа

У платформы три структуры ответа; клиент должен проверять и код состояния HTTP, и тело ответа.

Интерфейсы моделей, текста, изображений, видео и аудио

При успехе напрямую возвращается объект результата, при ошибке — HTTP не 2xx с объектом error:

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "size"
  }
}

Исключение — запрос видеозадачи: если задача не найдена, возвращается 400, а тело ответа имеет структуру верхнего уровня { code, message, data } (code — строка task_not_exist), а не объект error. Подробнее см. в разделе Коды ошибок и диагностика. Значения code, type и param зависят от типа ошибки; при диагностике ориентируйтесь в первую очередь на message, а не сопоставляйте только фиксированный текст code.

Интерфейсы библиотеки материалов

И при успехе, и при ошибке используется единая структура:

{ "code": 0, "data": {}, "msg": "OK" }

{ "code": 401, "data": null, "msg": "API Key 无效或已失效" }

При ошибке код состояния HTTP совпадает с code (400 / 401 / 404 / 429 / 502 / 503). Незавершённая проверка материала — не ошибка, а поле status в ответе 200 (Processing / Active / Failed).

Пагинация

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

В ответе data.total — общее количество записей, data.page и data.page_size — фактически применённые параметры пагинации. Всегда определяйте наличие следующей страницы по total, а не по «количеству записей в этом ответе».

Ограничение частоты запросов и повторные попытки

Повторяйте только 429 и кратковременные 5xx; 400, 401, 403, 404, 409 относятся к ошибкам запроса или прав доступа, повтор не поможет.

Идемпотентность и повторная отправка

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

• при каждом действии пользователя сначала создайте запись о бизнес-операции в собственной базе данных, и только затем вызывайте интерфейс платформы;
• при создании видеозадачи и отправке материала сохраняйте ID, возвращённый платформой, и перед повтором проверяйте, не создан ли объект;
• не отправляйте материал повторно, пока он находится в состоянии Processing, иначе будут созданы дубликаты материалов;
• тарификация основана на фактически успешно отправленных задачах; повторная отправка приводит к повторному списанию средств.

Рекомендуемый порядок вызовов

GET  /v1/models                     选择模型，确认能力与可用性
POST /api/v1/materials/groups       需要素材时创建分组
POST /api/v1/materials/assets       提交图片，保存 asset_id
GET  /api/v1/materials/assets/{id}  轮询到 status 为 Active
POST /v1/video/generations          提交视频任务，用 asset://<id> 引用素材
GET  /v1/video/generations/{id}     轮询任务，读取结果或错误

Рекомендации по серверной интеграции

1. Задавайте разумный тайм-аут для каждого запроса и различайте «тайм-аут» и «отмену пользователем»;
2. Для 429 и кратковременных 5xx выполняйте ограниченное число повторов с задержкой, остальные ошибки сразу возвращайте вызывающей стороне;
3. Сохраняйте номер бизнес-запроса, ID модели, ID материала, ID задачи и идентификатор запроса, возвращённый платформой, для упрощения диагностики;
4. Не записывайте API Key в логи, отчёты об ошибках, клиентскую аналитику или скриншоты;
5. Для больших файлов предпочтительно используйте публичный HTTPS-адрес объектного хранилища или ссылку asset:// из библиотеки материалов; не помещайте большие файлы в тело запроса.

Что дальше