Настройка API RunningHub Seedance 2.0: ключ, ресурсы и первый вызов

AI Overview

Какой способ настройки API RunningHub Seedance 2.0 самый быстрый?

Создайте API-ключ RunningHub, выберите точный маршрут AI-приложения или модели Seedance 2.0, отправьте один минимальный запрос, затем опрашивайте его taskId. Загрузки, вебхуки и механизмы повторных попыток для продакшена добавляйте только после успешного выполнения первого вызова.

Следует ли использовать AI App API или рабочий процесс ComfyUI?

Используйте AI App API, когда требуется фиксированный, размещённый контракт входных данных. Используйте OpenAPI-маршрут ComfyUI, когда вашей команде необходимы видимые сопоставления узлов, повторно используемые графы, подготовка ресурсов или шаги модели, изменяющиеся между проектами.

Как работают идентификаторы ресурсов (Seedance 2.0 asset IDs) в RunningHub?

Идентификаторы ресурсов позволяют поддерживаемым узлам Seedance 2.0 повторно использовать подготовленные ссылки. Интеграция ComfyUI принимает простые идентификаторы, значения вида asset://, разделённые списки или строку в формате JSON-массива, однако выбранный узел по-прежнему определяет допустимые слоты входных данных.

Почему URL завершённой задачи необходимо скопировать немедленно?

RunningHub предоставляет временные ссылки на медиафайлы для загрузок и сгенерированных результатов. Как только задача завершится успешно, немедленно переместите каждый утверждённый MP4-файл и постер в собственное долговременное хранилище; сохранённый идентификатор задачи не является постоянным архивом медиафайлов.

Что нужно подготовить перед первым вызовом

Надёжная настройка начинается с четырёх известных значений: региона API, действительного ключа, точного идентификатора AI-приложения или модели и целевого хранилища, находящегося под вашим контролем. Не копируйте конечную точку из стороннего руководства и не предполагайте совместимость её тела. RunningHub предоставляет несколько стилей вызовов, а каждая опубликованная страница с деталями API — это контракт для соответствующего маршрута. Более общее руководство по API Seedance 2.0 объясняет общий асинхронный шаблон; данное руководство сфокусировано исключительно на RunningHub.

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

export RH_API_BASE_URL="https://www.runninghub.cn/openapi/v2"
export RH_API_KEY="replace-with-your-key"

Используйте региональный базовый URL, указанный в вашей собственной консоли RunningHub и актуальной документации. Ключ потребителя может требовать наличия подходящего членства, тогда как корпоративные ключи могут иметь иные правила доступа. Проверка возможности просмотра модели в каталоге и возможность вызова этой модели с помощью вашего ключа — это два независимых условия.

Прежде чем тратить кредиты, определите один тестовый кадр (acceptance shot): один объект, одно действие, одно движение камеры, одна продолжительность и одно соотношение вывода. Если вы не уверены в жизнеспособности самого промпта, протестируйте творческое задание в рабочем пространстве модели Seedance 2.0. Это позволит отделить проблемы промпта от проблем интеграции.

Для первого вызова используйте визуально простой тестовый кадр. Этот свежий продукт-образец позволяет легко оценить силуэт, отражения, движение воды и стабильность фона; он не является эталонным тестом RunningHub.

Выбор правильного маршрута RunningHub

RunningHub предлагает два практических пути для решения этой задачи. Маршрут AI-приложения удобен, когда поставщик уже упаковал Seedance 2.0 в стабильное приложение с именованными входными параметрами. Вы отправляете запрос по этому идентификатору приложения и получаете taskId. Плагин OpenAPI ComfyUI предпочтительнее, когда сам граф входит в логику вашего продакшена или когда требуются вспомогательные средства для работы с ресурсами Seedance 2.0.

Не комбинируйте маршруты в первом тесте. Минимальный запрос к AI-приложению должен подтвердить аутентификацию, идентификатор приложения, отправку в очередь и получение результата. Минимальный вызов ComfyUI должен подтвердить, что экспортированный рабочий процесс выполняется без изменений до того, как вы добавите динамические переопределения nodeInfoList.

Официальный плагин RunningHub ComfyUI может считывать конфигурацию из узла настроек, переменных окружения или файла .env, причём настройки узла имеют приоритет. Зафиксируйте, какой уровень предоставил ключ. В противном случае коллега может обновить секрет в окружении, в то время как старое значение в узле будет продолжать применяться незаметно.

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

Пошаговая настройка API RunningHub Seedance 2.0

Начните с каркаса запроса, в котором открыты только те переменные, которыми ваш сервис действительно владеет. Текущая документация AI-приложений RunningHub показывает конечную точку вида /run/ai-app/{appId}, возвращающую объект задачи со статусами, например QUEUED, RUNNING, SUCCESS или FAILED. В качестве источника истины для имён полей используйте пример запроса, сгенерированный на точной странице с деталями API.

const response = await fetch(`${RUNNINGHUB_BASE}/run/ai-app/${APP_ID}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RH_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    nodeInfoList: inputMappings,
    webhookUrl: process.env.RH_WEBHOOK_URL
  })
});

if (!response.ok) throw new Error(`Submit failed: ${response.status}`);
const task = await response.json();
```Для рабочего процесса ComfyUI импортируйте один из соответствующих примеров, подключите `RH OpenAPI Settings` только в том случае, если вы не используете конфигурацию окружения, и запустите граф с использованием статических значений. После успешного выполнения оставьте доступными («экспортируйте») только те узлы, значения которых должны варьироваться — промпт, референс, продолжительность, соотношение сторон или параметры вывода — и сохраните идентификаторы этих узлов рядом с версией рабочего процесса.

Инструменты работы с ассетами RunningHub Seedance 2.0 добавляют ещё один вариант выбора. При установке `real_person_mode=false` используется прямая загрузка. При включении выбранные локальные слоты изображений или видео могут быть преобразованы в ассеты до отправки запроса к модели. Параметр `conversion_slots` определяет, какие именно слоты участвуют в этом процессе. Протестируйте сначала одно изображение: при передаче пакета из девяти изображений и трёх видео сложно определить, какое именно отображение вызвало сбой.

```official-video
src=https://r2.seedance.tv/blog/gpt-image-2-5-to-video-workflow/product-orbit-motion-v1.mp4
poster=https://r2.seedance.tv/blog/gpt-image-2-5-to-video-workflow/product-orbit-motion-poster-v1.jpg
label=Вертикальное видео вращения продукта для проверки результата полученного API-вызова

Этот воспроизводимый видеовыход Seedance демонстрирует, на что следует обратить внимание после получения результата: стабильную геометрию продукта, контролируемое движение камеры и чистый кадр. Он не представляет собой эталонный тест (бенчмарк) RunningHub.

Создание входных данных, сохраняющих свою целостность за пределами API-границы

API не может самостоятельно определить, какой файл является первым кадром, последним кадром, референсом персонажа или стиля. Перед отправкой подготовьте манифест входных данных. Укажите локальное имя файла, контрольную сумму исходного файла, MIME-тип, целевой слот, идентификатор ассета (если он был создан), а также метку промпта, ссылающуюся на этот файл. Такой подход гораздо полезнее, чем просто папка с файлами, названными, например, final-2.png.

{
  "shot": "kitchen-01",
  "references": [
    {"role": "first_frame", "assetId": "asset-example-01"},
    {"role": "style", "url": "https://your-storage.example/style.jpg"}
  ],
  "prompt": "Средний план с плавным следованием камеры; шеф-повар сервирует блюдо; поднимается пар; тёплое естественное освещение",
  "ratio": "16:9"
}

Документированная интеграция ComfyUI принимает один идентификатор ассета в формате asset://<asset_ID>, список значений, разделённых запятыми или символами новой строки, либо строку в формате JSON-массива. Эта гибкость удобна, однако надёжнее соблюдать единообразие: выберите один формат представления в вашем коде и проверяйте его корректность до запуска графа. Для преобразования изображения в видео интеграция распознаёт роли first_frame и last_frame; узлы мультимодального видео могут предоставлять несколько слотов для изображений и видео. Для тонкой настройки пакета референсов перед автоматизацией используйте рабочее пространство «референс в видео».

Формулируйте промпты как исполняемые инструкции по съёмке. Чётко разделяйте кадрирование, объект съёмки, действие, окружение, освещение и звук. Если первый вызов завершится творческим провалом, упростите лишь один компонент вместо одновременного изменения эндпоинта, ассетов, промпта и всего рабочего процесса. В статье «Рабочий процесс промптов для преобразования изображения в видео» представлен повторно используемый шаблон промптов.

Этот свежий финальный кадр демонстрирует тест с читаемыми руками, геометрией блюда, поднимающимся паром и естественным освещением — четыре детали, которые стоит проверить по всему сгенерированному видеоролику.

Опрос, сохранение и проверка результата

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

При статусе SUCCESS немедленно скопируйте MP4-файл. RunningHub указывает, что ссылки на сгенерированные результаты и ссылки для загрузки могут истекать через 24 часа. Поэтому загрузка файла только при открытии человеком экрана проверки считается небезопасной. Сохраните файл, его контрольную сумму, идентификатор задачи провайдера, версию промпта, исходный манифест и временную метку генерации в одном наборе данных. Затем создайте постер и прокси-файл, воспроизводимый в браузере, только если ваш стек доставки требует их наличия.

Видео движения кофе и пара для проверки тонких движений

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

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

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

Устранение распространённых ошибок API RunningHub Seedance 2.0

Классифицируйте ошибки по этапу жизненного цикла. Коды 401 и 403 указывают на проблемы с ключом, регионом, членством или правами доступа — а не с промптом. Запрос, отклонённый до получения taskId, обычно означает некорректный эндпоинт, идентификатор приложения, тип содержимого или структура тела запроса. Задача, застрявшая в очереди без прогресса, говорит о проблемах с очередью или истечении таймаута. Задача со статусом FAILED, содержащая детали проверки контента, требует более безопасного промпта или референса. Успешно завершённая задача с истёкшей ссылкой указывает на сбой хранения.| Симптом | Проверьте в первую очередь | Корректирующее действие | |---|---|---| | Неавторизованный доступ | Источник ключа и базовый регион | Удалите устаревшее переопределение узла; выполните ротацию ключа и повторно протестируйте минимальный вызов | | Недопустимое сопоставление узлов | Версия рабочего процесса и идентификаторы узлов | Экспортируйте текущий граф и обновите только те узлы, имена которых указаны явно | | Сбой преобразования ресурсов | Имя слота, его тип и доступность источника | Протестируйте один слот; используйте задокументированный резервный механизм прямой загрузки | | Задача остаётся в очереди | Интервал опроса и очередь учётной записи | Снизьте частоту опроса; не создавайте дублирующие задания автоматически | | URL результата истёк | Событие долговременного хранилища | Запустите повторное выполнение только в том случае, если исходный файл никогда не был скопирован | | Клип визуально некорректен | Промпт и исходный манифест | Оставьте API без изменений и скорректируйте лишь одну творческую переменную |

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

Если интеграция технически работает, но координация становится узким местом, используйте Seedance Agent, чтобы структурировать ссылки, превратить краткое ТЗ в последовательность кадров, сравнить утверждённые результаты и перезапустить только этап с ошибкой. Это решение уровня продакшена, а не замена глубокому пониманию базового API.

Заключение

Устойчивая настройка API RunningHub Seedance 2.0 — это жизненный цикл, а не просто успешная команда cURL: выберите правильное приложение ИИ или маршрут ComfyUI, храните ключ вне кода, подтвердите работоспособность на минимальном вызове, явно сопоставляйте ресурсы, сохраняйте taskId, снижайте частоту опроса при ожидании, немедленно копируйте временные результаты и оценивайте готовый клип по письменному чек-листу приёмки. Как только эти границы станут стабильными, добавьте вебхуки, расширенные мультимодальные входные данные, планирование пакетных заданий и ручное одобрение — не маскируя сбои избыточной автоматизацией. Чтобы планировать ссылки и кадры до расходования бюджета и обеспечивать прохождение утверждённых материалов через проверку и целенаправленные повторные запуски, начните проект с Seedance Agent.