Руководство
Ограничения частоты и квоты
Лимиты параллельных задач, ограничения частоты запросов, квоты и ёмкость аккаунта, а также повторные попытки с задержкой
Ограничения частоты и квоты
Ограничения платформы делятся на несколько категорий, и проявляются они по-разному. Чтобы быстро реагировать, важно понимать, к какой категории относится ограничение.
| Тип ограничения | Проявление при срабатывании | Как обрабатывать |
|---|---|---|
| Частота запросов (ограничение частоты) | HTTP 429 «Слишком много запросов» | Повторите с задержкой, не повторяйте параллельно |
| Параллельные асинхронные задачи | HTTP 429, task_concurrency_exceeded | Дождитесь завершения существующих задач, затем отправляйте |
| Квота Key | Сообщение о недостатке баланса/квоты, задача не создаётся | Пополните баланс, измените квоту Key или уменьшите запрос |
| Баланс аккаунта | Сообщение о недостатке баланса для покрытия предварительной оценки | Пополните кошелёк |
| Ёмкость материалов | Проверка формата и размера при отправке материала | Исправьте файл или используйте image_url |
Ограничение частоты запросов
Платформа ограничивает частоту запросов. Слишком частый опрос, слишком высокая параллельность или массовые повторные попытки за короткое время могут вызвать:
{ "error": { "code": "...", "message": "请求过于频繁" } }HTTP-статус — 429.
Правильный подход:
- после получения
429сделайте паузу: подождите некоторое время перед следующим запросом, не отправляйте сразу; - не пытайтесь обойти ограничение параллельными запросами — это лишь увеличит время ожидания;
- при опросе асинхронных задач используйте фиксированный разумный интервал (например, раз в несколько секунд), не опрашивайте без пауз.
Не повторяйте вслепую при кодах, отличных от 429:
| Код статуса | Обработка |
|---|---|
429 | Сделайте паузу по указанию и повторите |
Кратковременный 5xx | Сохраните RequestId и повторите один раз после паузы |
400 | Проблема с параметрами — исправьте запрос и отправьте снова |
401 | Key недействителен или отключён — проверьте ключ |
403 | Нет прав на доступ к ресурсу или модели |
404 | Ресурс не существует — проверьте ID |
Параллельные асинхронные задачи
Асинхронные задачи, например видео, ограничены лимитом параллельных задач, который действует
на уровне отдельного аккаунта и на уровне всей платформы. При достижении лимита возвращается HTTP 429
с кодом ошибки task_concurrency_exceeded, а в сообщении указывается «текущее N / лимит M».
В этом случае следует:
- сохранить ID существующих задач и не отбрасывать их;
- дождаться перехода выполняющихся задач в терминальное состояние (или запросить их текущий статус);
- отправлять повторно только после ожидания и по инициативе пользователя, не повторять подряд;
- не отправляйте одну и ту же задачу повторно, чтобы «занять» параллельный слот, — это создаст дублирующиеся задачи и повторные расходы.
Перед массовой отправкой рекомендуется организовать очередь на бэкенде: контролируйте количество выполняющихся задач, а не отправляйте всё сразу.
Квота Key и баланс аккаунта
Квота и баланс — это два уровня ограничений:
| Уровень | Описание |
|---|---|
| Квота Key | Лимит использования и срок действия, заданные для Key в разделе «Ключи API» консоли |
| Баланс аккаунта | Доступный баланс, квота тарифа или баллы всего аккаунта LocoPal |
Перед отправкой асинхронной задачи платформа проверяет, покрывает ли баланс предварительную оценку расхода. При недостатке возвращается читаемое сообщение и задача не создаётся, поэтому в этом случае расходы не возникают.
Как обрабатывать:
- недостаточная квота Key → измените квоту или срок действия этого Key в разделе «Ключи API»;
- недостаточный баланс аккаунта → пополните «Кошелёк» или используйте тариф;
- слишком большая предварительная оценка → уменьшите разрешение, длительность или переключитесь на меньшую модель.
Рекомендуется на бэкенде заранее проверять баланс и показывать конечному пользователю понятное сообщение, а не передавать ему ошибку платформы напрямую.
Ограничения материалов
Интерфейс материалов проверяет загружаемые данные:
| Ограничение | Проявление | Обработка |
|---|---|---|
| Формат адреса | image_url 必须是可公开下载的 http(s) 地址… | Используйте адрес http(s), доступный для прямой загрузки из публичной сети |
| Один тип за раз | image_url 与 data_url 只能提交一个 | Оставьте только одно поле |
| Размер данных | 图片数据无效或超过 20MB | Сожмите изображение или используйте image_url |
| Тип группы | 素材分组不存在或不是虚拟素材分组 | Изображения можно отправлять только в группу virtual |
| Длина названия | Название группы не может быть пустым и не должно превышать 64 символа; описание — не более 300 символов | Исправьте название или описание |
Незавершённая проверка материала — не ошибка: при запросе возвращается 200 со status = Processing;
продолжайте опрашивать с тем же ID материала, не отправляйте повторно.
Рекомендации по опросу
Запросы асинхронных задач не создают расходов, но слишком частый опрос вызывает ограничение частоты.
| Этап задачи | Рекомендуемый интервал |
|---|---|
| Только что отправлена (в очереди) | Раз в несколько секунд |
| Генерация | Раз в несколько секунд — до десяти-двух десятков секунд |
| Достигнуто терминальное состояние | Прекратите опрос |
У опроса должен быть общий лимит времени. По достижении лимита прекратите запросы и верните пользователю ID задачи, чтобы он мог позже продолжить запросы по ID — не создавайте задачу заново.
Идемпотентность и повторные отправки
Платформа не объединяет одинаковые запросы автоматически. Даже при полностью одинаковых промпте, параметрах и референсных материалах каждая отправка создаёт новую задачу и новый результат, и каждая тарифицируется отдельно.
Поэтому:
- используйте идемпотентные ключи на стороне бизнеса (номер заказа, бизнес-ID), чтобы повторные нажатия пользователя не приводили к повторной отправке;
- сразу после отправки асинхронной задачи сохраняйте ID задачи в базе данных; при обрыве сети восстанавливайте состояние запросами, а не повторным созданием;
- только при нажатии «Повторить напрямую» для одного и того же неудачного результата выполнение повторяется на месте — это также создаёт новую задачу и новые расходы.