Pro API: лимиты, коды ошибок и рекомендации

Лимиты

У каждого ключа их три: одновременных рендеров (по умолчанию 2), запросов в минуту (по умолчанию 60) и, если ты его задал, дневной лимит кредитов.

При превышении лимита ответ, 429 с заголовком Retry-After в секундах. Отклонённый вызов ничего не стоит. Сутки для лимитов отсчитываются по UTC.

Длинные видео добавляют ещё два лимита: 30 кадров на последовательность и 5 последовательностей в работе на лицензию (см. Videos).

У персонажей один лимит: 50 на Pro-лицензию, включая созданных в приложении, а персонаж, не используемый один год, удаляется (см. Characters). Места, объекты и животные имеют собственный лимит, учитываемый отдельно: 50 на Pro-лицензию (10 с персональной лицензией в приложении), удаляются после того же года без использования (см. Места, объекты, животные, стили и наряды).

Face swap имеет два собственных лимита: отрывок не более 20 с на рендер, и наш сервер обрабатывает два видео одновременно. При превышении ответ, 429 server_busy: повтори после Retry-After (см. Face swap). Через MCP Face swap с переходом принимает всё видео целиком не более 60 с, а сервер обрабатывает два одновременно: сверх этого инструмент просит повторить попытку через несколько минут.

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

Коды ошибок

Код	error	Что означает и что делать
400	prompt_required	Добавь промпт.
400	forbidden_content	Фильтр контента отклонил промпт.
400	invalid_seed	seed должен быть целым числом от 0 до 4294967295.
400	image_required, inpaint_images_required	Режим требует image_b64, а для inpaint ещё и mask_b64.
401	key_required, invalid_key	Заголовок отсутствует или ключ неизвестен.
402	insufficient_credits	Недостаточно баланса для этого рендера (указана cost). В ответе есть buy_url: страница покупки кредитов для твоей лицензии. Рендер или обучение, выполняемые в данный момент, резервируют свою стоимость до завершения: engaged показывает, сколько кредитов зарезервировано.
402	confirmation_required, payment_declined	Покупка с сохранённой карты (POST /credits/purchase): банк просит твоего подтверждения или отклонил платёж. Воспользуйся buy_url, обычной ссылкой на покупку.
409	agent_not_allowed, no_saved_card, monthly_cap_reached	Покупка с сохранённой карты: агенту не разрешено покупать (автопополнение на странице аккаунта), карта не сохранена, или покупка превысила бы твой месячный лимит. Воспользуйся buy_url.
409	topup_in_progress, purchase_in_progress	Идёт другой платёж с сохранённой карты: дождись его завершения.
400	unknown_pack	Покупка с неизвестным пакетом или с произвольным количеством вне допустимых границ или не кратным шагу.
503	payment_unavailable	Платёж не удалось подтвердить: мы не знаем, прошло ли списание. Не повторяй сразу; прошедшее списание будет зачислено.
403	key_disabled, key_revoked, key_expired	Ключ отключён, отозван или истёк срок действия: создай новый в приложении.
403	license_revoked, license_not_pro	Лицензия отозвана или аккаунт не является Pro.
403	missing_scope	Ключу не хватает запрошенного разрешения, его название указано в scope.
403	unknown_lora	Персонаж не принадлежит этому аккаунту.
404	media_unavailable	Файл удалён: отправь запрос заново.
404	unknown_lora	При DELETE /loras/{name} файла с таким именем нет в аккаунте. Обрати внимание на код: то же имя даёт 403, когда рендер запрашивает персонажа, который тебе не принадлежит.
411	size_required	Загрузка LoRA без Content-Length. Тело передаётся как есть, поэтому размер нужно объявить заранее.
413	file_too_large	LoRA превышает 800 МБ или 90 МБ в одной загрузке. Отправь по частям. Простой 413 без JSON-тела, другая ситуация: запрос вообще не дошёл до API, см. раздел про загрузку.
413	part_too_large	Одна часть превышает max_part_size, объявленный сессией.
404	unknown_upload_session	uploadId не существует, либо сессия была заброшена (шесть часов) или отменена из-за отклонённой части.
503	upload_refused, part_refused	Хранилище не было доступно во время загрузки: повтори попытку.
507	storage_full	На серверном хранилище нет свободного места (LoRA или незавершённые последовательности). Команда уведомлена: повтори позже.
415	invalid_safetensors	Загруженный файл не является safetensors.
415	incompatible_lora	LoRA предназначена для другой архитектуры, указанной в architecture. Изображения принимают только Krea 2, видео, LTX 2.5 или 2.3. Ничего не сохраняется, квота не расходуется.
413	lora_quota	Хранилище LoRA аккаунта заполнено (20 файлов или 10 ГБ). В ответе указано, что осталось; удали файл, чтобы освободить место.
413	image_too_large	Исходное изображение или маска превышают 12 МБ после декодирования.
429	too_many_concurrent_renders, rate_limited, daily_cap	Лимит достигнут, см. Retry-After.
429	daily_credit_cap	Достигнут дневной лимит кредитов ключа (cap, spent, cost).
502	submission_failed, status_failed	Инцидент на стороне рендеринга: повтори через несколько секунд.
503	license_check_failed	Аккаунт не удаётся проверить прямо сейчас: повтори через минуту.
400	invalid_extend_frames	Продолжение, у которого extend_frames не равен 9, 17, 25, 33, 41 или 49, либо extend_video, у которого не ровно столько кадров.
400	extension_with_transition	Продолжение не может одновременно быть переходом, кроме случая consistency enhanced: убери end_image или запроси усиленную согласованность.
400	extension_too_short	length продолжения учитывает только новые кадры и должен быть не менее 9.
404	clip_unavailable	Клип для продолжения больше недоступен: продолжи его раньше или передай его конец в extend_video. При 502 не удалось его прочитать: повтори.
404	unknown_clip	Клип для продолжения принадлежит другой лицензии.
404	unknown_sequence	Последовательность не существует, принадлежит другой лицензии или истекла.
400	job_id_required, empty_sequence	POST /sequences/{id}/clips без job_id или экспорт последовательности без ни одного кадра.
409	not_exported_yet	GET /sequences/{id}/file до экспорта: сначала вызови POST /sequences/{id}/export.
404	unknown_export	Экспорт папки проекта: неизвестный рендер, рендер другой лицензии или отправленный более 24 ч назад; ZIP удалён (через 45 мин после первого скачивания, не позднее 2 ч).
409	export_in_progress	Один экспорт папки проекта одновременно на лицензию.
413	export_too_large	Папка проекта больше 2 ГБ: экспортируй кадры по одному.
400	unknown_reference	Экспорт папки проекта: элемент exclude_references не указывает ни на один референс экспорта (ни id, ни имя, ни @упоминание).
400	invalid_export_options	Экспорт папки проекта: параметр, который не является булевым, exclude_references, который не является списком строк, или include_film без include_media.
500	export_failed	Экспорт не удался (причина в detail): ничего не списано, попробуй снова.
422	resolution_mismatch, unreadable_clip	Рендер, добавленный вручную (POST /sequences/{id}/clips) с разрешением, отличным от разрешения последовательности, или нечитаемый.
409	missing_shot	Кадр ещё не готов или больше недоступен (job_id его называет): дождись завершения, затем снова экспортируй.
409	sequence_exported	Последовательность уже собрана.
409	audio_mismatch	Кадр со звуком в беззвучной последовательности или наоборот.
413	extend_video_too_large	Конец клипа, который ты отправил, превышает 8 МБ.
413	too_many_shots	Не более 30 кадров на последовательность.
422	unreadable_tail	Конец клипа, отправленный или считанный обратно, не является читаемым видео.
422	assembly_failed	Кадры имеют разное разрешение или звук только у некоторых из них.
503	ultra_unavailable	Режим Ультра временно недоступен: повтори позже или создай рендер без quality.
503	ultra_4k_unavailable	Размер 4K запрошен в Ультра: 4K больше не предлагается, видео доступно до 1080p (1920 x 1088).
400	ultra_incompatible	Переход (end_image) запрошен в режиме Ультра.
400	extension_4k	Продолжение прежнего 4K-клипа: 4K больше не предлагается, 4K-клип нельзя продлить (ultra_4k_unavailable с quality: "max"). Продлевай клип не выше 1080p.
400	resolution_above_quality	Размер выше 1080p (1920 x 1088) без quality: "max": максимум 1080p в любом режиме.
400	invalid_keyframes, invalid_keyframe_time, keyframes_mode	Ключевые кадры вне допустимых границ: более 4, недопустимое изображение или сила; момент за пределами клипа или два ключевых кадра ближе 0,5 с друг к другу; режим, отличный от Качество (Ультра, Multi-Ref), или продолжение без consistency enhanced.
400	invalid_consistency, consistency_mode	consistency отличается от standard или enhanced; усиленная согласованность запрошена в Ультра или в Multi-Ref.
400	consistency_explicit	Промпт, который усиленная согласованность пока не обрабатывает, длиннее 20 с (15 с при наличии end_image), в продолжении или в последовательности (один более короткий кадр обрабатывается со стандартной согласованностью): укороти его или используй standard.
403	consistency_licensed_only	Усиленная согласованность доступна только для лицензий.
503	consistency_unavailable	Усиленная согласованность временно недоступна: повтори позже или создай рендер в standard.
409	consistency_mismatch	Кадр, у которого consistency отличается от значения последовательности.
422	encoding_mismatch	Рендер, добавленный вручную (POST /sequences/{id}/clips), у которого consistency отличается от уже добавленных кадров.
400	invalid_fps, fps_requires_fixed_duration, extend_fps_mismatch	Частота кадров (fps), которую режим не поддерживает (detail перечисляет доступные); усиленная согласованность выше 30 fps с автоматической длительностью (задай duration_auto как false и укажи length); продолжение с частотой кадров, отличной от предыдущего клипа.
409	sequence_fps_mismatch	Кадр, у которого частота кадров (fps) отличается от значения последовательности.
503	keyframes_unavailable	Ключевые кадры временно недоступны: создай рендер без keyframes.
429	too_many_sequences	Не более 5 последовательностей в работе на лицензию: экспортируй одну или дождись истечения срока.
400	invalid_name, invalid_kind, invalid_photo_role, outfit_too_long, invalid_role	Поле персонажа вне допустимых границ (см. Characters).
400	image_too_small	Фотография меньше 1024 пкс по длинной стороне.
415	unsupported_image_format, unreadable_image	Фотография или изображение локации не является читаемым JPEG, PNG или WebP.
404	unknown_character	character_id не привязан к твоей лицензии или был удалён (год без использования или удалён в приложении).
409	character_limit	Достигнут лимит персонажей (max): удали одного.
409	character_busy	Его ракурсы создаются: дождись, пока status перестанет быть pending. Для POST /characters: то же создание ещё сохраняется, отправь его снова через несколько секунд.
409	photo_view, empty_character, single_image_sheet	Ракурс, полученный из оригинальной фотографии, нельзя переделать; или у персонажа нет ни одного читаемого ракурса (если чтение отклоняет хранилище: 503 storage_unavailable, повторите попытку); или sheet, импортированный одним изображением (сохранённый как есть): его ракурсы не переделываются, и он не одевает новый sheet (передайте ракурс 4 или 1).
409	app_character	instruction или загруженный ракурс для персонажа или character sheet из приложения: зарезервировано для персонажей и character sheet, созданных через API.
400	instruction_too_long	instruction длиннее 200 символов.
400	outfit_or_views_required	Character sheet добавлен без outfit и без views: укажи образ для генерации или ракурсы.
400	views_required	Character sheet добавлен с generate: false: укажи хотя бы один ракурс.
409	source_sheet_empty	Character sheet добавлен без ракурса в полный рост и без бюста персонажу, у которого нет ни того, ни другого, чтобы взять за основу: пришли один из них в views.
404	unknown_sheet	Через DELETE /characters/{id}/sheets/{sheet_id} удаляется только character sheet, добавленный через API (sheet_origin api).
404	unknown_subject	subject_id не привязан к твоей лицензии или был удалён после года без использования.
409	subject_limit	Достигнут лимит объектов (max): места, предметы, животные, стили и наряды считаются вместе; удали один.
409	empty_subject	Объект без ни одного читаемого изображения.
400	invalid_type, description_too_long, invalid_images	Поле объекта вне допустимых границ (см. Места, объекты, животные, стили и наряды).
400	invalid_image	Изображение объекта не является читаемым JPEG, PNG или WebP размером не менее 512 пкс по длинной стороне (index указывает, какое именно).
400	description_required, invalid_views, invalid_view, invalid_count, too_many_images, prompt_too_long, invalid_instructions	Генерация объекта: нет ни description, ни prompt, ни стартового изображения; ключ ракурса, которого нет у типа (detail даёт список); count вне диапазона от 1 до 6 или больше 6 изображений, включая старт; prompt длиннее 2000 символов; instructions пустые, слишком длинные или для нескольких ракурсов.
409	subject_busy, subject_not_generated, view_exists, views_exist, start_image_missing, start_image_imported	Серия на этом объекте уже идёт; объект создан из изображений (добавляй изображения через /images); ракурс уже сделан (переделай его); старт нужно переделать, а из него уже исходят ракурсы; неудачный старт нужно сначала переделать; импортированный старт, который не переделывается.
404 / 503	unknown_view, generation_unavailable	Ракурс, который никогда не запрашивали (добавь его); генерация объектов сейчас недоступна на сервере: повтори позже.
400	multiref_characters_required, multiref_incompatible, multiref_mode, multiref_format, invalid_length	Multi-Ref вне допустимых границ: от 1 до 4 персонажей (12 в Ультра), без продолжений или переходов, форматы и длительности из Multi-Ref Video.
400	duplicate_name, invalid_strength, unknown_mention	Два персонажа с одинаковым именем; strength вне диапазона от 0 до 2; @Имя в промпте без персонажа (mentions их перечисляет).
400	voice_requires_audio, voice_slot	Голос персонажа (voice_b64) без звука ("audio": true); или для персонажа, отличного от characters[0] и characters[1] (движок поддерживает 2 голоса). index указывает, какой именно.
400	invalid_voice_choice	voice отличается от character или original в Face swap, или characters[].voice отличается от character или generated в Multi-Ref Видео.
413	audio_too_large	Голос персонажа превышает 4 МБ или 2 МБ в Face swap. Используются только первые 5 секунд (20 в Face swap): отправь короткий фрагмент.
415	unsupported_audio_format	Голос персонажа не является читаемым аудиофайлом (WAV, MP3, OGG, FLAC).
400	multiref_too_many_references, invalid_subject_type	Более 4 персонажей, объектов и животных суммарно вне Ультра; объект в неверном поле (локация в subjects, предмет как location, стиль вне styles, наряд вне outfits).
400	invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size	Создать изображение: count 1 или 2, view от 1 до 5 и присутствует в character sheet, lora_pass от 0,3 до 0,9, image объекта из числа его изображений, ширина и высота от 256 до 2048.
400	character_not_ready	Создать изображение: у выбранного ракурса персонажа ещё нет изображения.
503	multiref_image_disabled	Создание изображения на этом сервере ещё не открыто.
400	multiref_ultra_only, multiref_too_many_images, unknown_wearer	Стили, наряды или движение вне Multi-Ref в Ультра; более 30 изображений в Ультра; worn_by, не называющее ни одного персонажа.
400	invalid_motion, invalid_motion_mode, unreadable_motion, motion_missing	motion без motion_id и без video_b64; mode кроме camera или choreography; нечитаемое видео или видео вне диапазона от 4 до 30 с (input_video_out_of_limits); motion_id, который так и не был загружен (нет PUT).
404 / 409	unknown_motion, motion_already_used	motion_id неизвестен, уже использован или старше 2 часов: загрузи видео заново.
413 / 503	motion_too_large, motion_not_open, motion_mode_unavailable	Видео движения больше 20 МБ (20 МБ после приведения к 480p); движение пока не открыто (ultra.motion_per_second равно null); mode, который пока не открыт.
409	extension_link_expired	extend_job_id, неизвестный твоей лицензии, или план Ультра старше 24 часов: загрузи его оригинал (POST /extensions) и передай extend_upload_id.
400	extension_real_face	Видео для продления в Ультра отрендерено не в режиме Ультра (например, рендер другого режима), и на нём реалистичное лицо: ничего не списывается. Продли его в режиме Качество или переделай план в Ультра.
400	extension_ultra_only, extension_ultra_options, invalid_extension_direction, extension_backward_sequence, extension_tail_quality_only	Расширение Ультра вне допустимых рамок: extend_upload_id или backward без quality: "max" (или из клипа не в Ультра); начальное изображение, референсы, движение или усиленная согласованность вместе с ним; направление кроме forward или backward; backward в последовательности; extend_video в Ультра.
400	extension_too_large, unreadable_extension, extension_upload_missing	Загруженное видео выше 1080p; нечитаемый MP4 или вне диапазона от 4 до 30 с (input_video_out_of_limits); файл, который так и не был загружен (нет PUT).
400	input_video_out_of_limits	Видео, отправленное в режим Ultra (движение, видео для продления), вне его пределов, проверенных перед рендером, ничего не списано: limit указывает, какой (duration: от 4 до 30 с; total_duration: 30 с вместе с опорными звуками; count: 10; size: 200 МБ; format: MP4 или MOV; fps: от 24 до 60; pixels: ширина × высота от 409 600 до 8 295 044; aspect_ratio: от 0,4 до 2,5), с value, min и max.
404 / 409	unknown_extension_upload, extension_upload_used	extend_upload_id неизвестен, старше 2 часов или уже использован: загрузи файл заново.
413 / 503	extension_too_heavy, extension_not_open, extension_backward_unavailable	Файл больше 60 МБ; расширение Ультра пока не открыто (ultra.extend_per_second равно null); назад пока не открыто.
413	references_too_large	Подготовленные ракурсы превышают бюджет рендера: используй меньше персонажей или меньший формат.
400	video_required, character_required	Face swap без video_b64 или без character_id.
413	video_too_large	Видео для Face swap превышает 20 МБ: обрежь или сожми его заранее, либо используй MCP-инструмент tendre_face_swap, который принимает до 95 МБ.
415	unreadable_video	Видео для Face swap не является читаемым MP4, MOV, WebM или MKV.
400	invalid_start, invalid_duration, passage_too_short	Отрывок Face swap вне допустимых границ: start меньше 0 или за концом видео; duration вне диапазона от 0,5 до 20 с; отрывок короче полсекунды.
400	invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part	Поле Face swap вне допустимых границ: zone отличается от tight, normal или wide; part отличается от full или head; likeness вне диапазона от 0,5 до 2; scene длиннее 400 символов; description длиннее 360; name длиннее 60.
413	face_swap_too_large	Отрывок после подготовки всё равно слишком тяжёлый: задай меньшую duration.
429	server_busy	Наш сервер уже обрабатывает два видео Face swap: повтори после Retry-After (20 с). Ссылка для загрузки MCP отвечает тем же кодом как 503, когда слишком много файлов в очереди: повтори через несколько минут.
503	face_swap_unavailable, face_swap_price_missing	Face swap закрыт или не имеет цены прямо сейчас: повтори позже.
503	creation_unavailable, multiref_unavailable, storage_unavailable	Сервис временно недоступен: повтори позже.
500	internal_error	Непредвиденный инцидент на стороне сервера: повтори попытку и сообщи нам, если это повторится.

Ультра с посекундной оплатой (Ultra):

Код	error	Что означает и что делать
400	resolution_outside_ultra	Выше 1080p: 480p, 720p или 1080p.
400	engine_refused	Движок отклоняет текст или изображение: причина в detail, код в code. Ничего не списывается: переформулируй.
502	engine_unavailable	Движок не отвечает: повтори через несколько минут. Ничего не списывается.
409	render_in_progress	Отмена рендера, который уже рассчитывается: он больше не останавливается, доставляется и оплачивается.
400	invalid_references, references_too_large, multiref_ultra_options, multiref_ultra_explicit	Multi-Ref в Ультра: референсное изображение нечитаемо или слишком тяжёлое (не более 20 МБ в сумме), или опция не поддерживается.
403	multiref_ultra_unavailable	Multi-Ref в Ультра с посекундной оплатой ещё не открыт для этого аккаунта.

Названия ошибок, точные строки, которые возвращает API. Сопоставляй по ним, а не по сообщению, которое может быть переформулировано.

Один ответ не является ошибкой: рендер Multi-Ref или Face swap с персонажем, у которого только один ракурс, проходит, но в warnings появляется предупреждение limited_likeness ({ "code": "limited_likeness", "character_id": "...", "detail": "..." }). Сходство будет ограниченным: создай семь ракурсов персонажа для точного сходства.

Рендер Multi-Ref в Ультра с 9-12 персонажами тоже проходит, с предупреждением many_characters: некоторые могут пропасть или смешаться (рекомендуется 8).

Рекомендации

• Опрашивай каждые 3 секунды, не чаще. Очередь общая, и её перегрузка никому не помогает.
• Скачивай сразу, как только статус становится completed. Файл не архивируется.
• Пиши промпты на английском, а для видео описывай движение, а не статичную картинку.
• Один ключ на задачу и дневной лимит кредитов на каждом ключе, живущем на сервере. Утечка ключа с лимитом обойдётся тебе в один день, а не в весь баланс.
• Относись к 429 как к норме, а не к ошибке: подожди Retry-After и продолжай.
• Соединение, оборвавшееся до ответа, ничего не стоит. Если отправка изображения или видео осталась без ответа (истёк тайм-аут прокси, ошибка 524, программа остановлена), рендер не запускается или сразу отменяется, и ничего не списывается: просто отправь запрос ещё раз. Для серии изображений (count) уже созданные рендеры тоже отменяются. Создание персонажа при этом продолжается: повторная отправка того же запроса вернёт того же персонажа, без двойного списания (см. Characters).

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