Configuração da API RunningHub Seedance 2.0: Chave, Ativos e Primeira Chamada

AI Overview

Qual é a maneira mais rápida de configurar a API RunningHub Seedance 2.0?

Crie uma chave de API RunningHub, escolha a rota exata do aplicativo de IA Seedance 2.0 ou do modelo, envie uma solicitação mínima e, em seguida, consulte seu campo taskId. Adicione uploads, webhooks e tentativas de repetição em produção somente após essa primeira chamada ter sucesso.

Devo usar o AI App API ou um fluxo de trabalho ComfyUI?

Use o AI App API quando desejar um contrato de entrada fixo e hospedado. Use a rota OpenAPI ComfyUI quando sua equipe precisar de mapeamentos de nós visíveis, gráficos reutilizáveis, preparação de ativos ou etapas de modelo que variam entre projetos.

Como os IDs de ativos Seedance 2.0 funcionam no RunningHub?

Os IDs de ativos permitem que nós compatíveis de Seedance 2.0 reutilizem referências previamente preparadas. A integração ComfyUI aceita IDs simples, valores no formato asset://, listas separadas por vírgulas ou uma string JSON em formato de array; contudo, o nó escolhido ainda determina quais slots de entrada são válidos.

Por que a URL de uma tarefa concluída precisa ser copiada imediatamente?

O RunningHub fornece links temporários para mídias enviadas e resultados gerados. Mova imediatamente todos os arquivos MP4 e posters aprovados para seu próprio armazenamento durável assim que a tarefa for bem-sucedida; um ID de tarefa armazenado não equivale a um arquivo permanente de mídia.

O Que Você Precisa Antes da Sua Primeira Chamada

Uma configuração confiável começa com quatro valores conhecidos: a região da API, uma chave válida, o identificador exato do aplicativo de IA ou modelo e um destino de armazenamento sob seu controle. Não copie um endpoint de um tutorial não relacionado assumindo que seu corpo será compatível. O RunningHub expõe diversos estilos de chamada, e cada página detalhada da API publicada representa o contrato oficial para aquela rota. O guia geral da API Seedance 2.0 explica o padrão assíncrono geral; este guia mantém o foco estrito no RunningHub.

Mantenha a chave fora do controle de versão. Para a integração oficial ComfyUI, o padrão documentado de variáveis de ambiente é:

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

Use a URL base regional exibida no seu próprio console RunningHub e na documentação atual. Uma chave de consumidor pode exigir uma associação elegível, enquanto chaves empresariais podem ter regras de acesso distintas. Trate a capacidade de visualizar um modelo no catálogo e a capacidade de chamá-lo com sua chave como duas verificações independentes.

Antes de consumir créditos, defina um shot de aceitação: um único sujeito, uma única ação, um único movimento de câmera, uma única duração e uma única proporção de entrega. Se tiver dúvidas sobre a viabilidade do prompt, teste-o primeiro no espaço de trabalho do modelo Seedance 2.0. Isso separa problemas relacionados ao prompt de problemas de integração.

Use um quadro de aceitação visualmente simples para a primeira chamada. Essa imagem recente do produto facilita a inspeção de silhuetas, reflexos, movimento da água e estabilidade do fundo; ela não é um benchmark oficial do RunningHub.

Escolha a Rota RunningHub Certa

O RunningHub oferece dois caminhos práticos para essa tarefa. A rota do Aplicativo de IA é útil quando o provedor já empacotou o Seedance 2.0 em um aplicativo estável com entradas nomeadas. Você submete àquele ID de aplicativo e recebe um taskId. O plugin OpenAPI ComfyUI é mais adequado quando o próprio grafo faz parte da sua lógica de produção ou quando você precisa dos auxiliares de ativos Seedance 2.0.

Não combine as rotas no seu primeiro teste. Uma solicitação mínima ao Aplicativo de IA deve comprovar autenticação, identificador do aplicativo, submissão à fila e recuperação do resultado. Uma chamada mínima ao ComfyUI deve comprovar que o fluxo de trabalho exportado executa-se sem alterações antes de você introduzir substituições dinâmicas de nodeInfoList.

O plugin oficial RunningHub ComfyUI pode ler a configuração de um nó de configurações, variáveis de ambiente ou de um arquivo .env, com as configurações do nó tendo prioridade. Registre qual camada forneceu a chave. Caso contrário, um colega poderá rotacionar o segredo de ambiente enquanto um valor antigo no nó continuar prevalecendo silenciosamente.

Um shot rico em referências deve manter legíveis a pessoa, a vestimenta, o animal, o clima e o local. A imagem é uma saída ilustrativa recente, não uma comparação oficial entre modelos.

Configuração Passo a Passo da API RunningHub Seedance 2.0

Comece com um esqueleto de solicitação que exponha apenas variáveis realmente controladas pelo seu serviço. A documentação atual do Aplicativo de IA do RunningHub mostra um endpoint no formato /run/ai-app/{appId} e retorna um objeto de tarefa com estados como QUEUED, RUNNING, SUCCESS ou FAILED. Use o exemplo de solicitação gerado na página exata de detalhes da API como fonte verdadeira para os nomes dos campos.

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(`Falha ao submeter: ${response.status}`);
const task = await response.json();
```Para um fluxo de trabalho ComfyUI, importe um dos exemplos correspondentes, conecte apenas `RH OpenAPI Settings` se você *não* estiver usando configuração de ambiente e execute o grafo com valores estáticos. Após funcionar corretamente, exponha somente os nós que precisam variar — prompt, referência, duração, proporção ou opções de saída — e armazene esses IDs de nó ao lado da versão do fluxo de trabalho.

As ferramentas de ativos RunningHub Seedance 2.0 adicionam outra opção. `real_person_mode=false` segue o caminho de upload direto. Quando ativado, slots locais selecionados de imagem ou vídeo podem ser convertidos em ativos antes da requisição ao modelo. `conversion_slots` controla quais slots participam. Teste primeiro uma única imagem, pois uma carga com nove imagens e três vídeos oculta qual mapeamento causou a falha.

```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=Vídeo vertical de órbita de produto para verificação de um resultado recuperado da API

Essa saída de movimento Seedance reproduzível demonstra o que inspecionar após a recuperação: geometria estável do produto, movimento controlado da câmera e quadro limpo. Não é apresentada como um benchmark de RunningHub.

Construa entradas que sobrevivam à fronteira da API

A API não consegue inferir qual arquivo é o quadro inicial, o quadro final, uma referência de personagem ou uma referência de estilo. Crie um manifesto de entrada antes do envio. Armazene um nome local, soma de verificação (checksum) da fonte, tipo MIME, slot pretendido, ID do ativo (se criado) e o rótulo do prompt que o referencia. Isso é mais útil do que uma pasta de arquivos chamada final-2.png.

{
  "shot": "kitchen-01",
  "references": [
    {"role": "first_frame", "assetId": "asset-example-01"},
    {"role": "style", "url": "https://your-storage.example/style.jpg"}
  ],
  "prompt": "Plano médio de acompanhamento; chef serve o prato; vapor sobe; iluminação prática quente",
  "ratio": "16:9"
}

A integração documentada de ComfyUI aceita um único ID de ativo, um valor asset://<asset_ID>, valores separados por vírgula ou quebra de linha, ou uma string em formato JSON-array. Essa flexibilidade é conveniente, mas a consistência é mais segura: escolha uma única representação em seu código-base e valide-a antes da execução do grafo. Para image-to-video, a integração identifica first_frame e last_frame; nós multimodais de vídeo podem expor múltiplos slots de imagem e vídeo. Use o espaço de trabalho reference-to-video para refinar um pacote de referências antes de automatizá-lo.

Escreva prompts como instruções executáveis de tomada. Separe enquadramento, sujeito, ação, ambiente, iluminação e som. Se a primeira chamada falhar criativamente, simplifique apenas um canal em vez de alterar simultaneamente o endpoint, os ativos, o prompt e o fluxo de trabalho. O fluxo de trabalho de prompt para image-to-video fornece um padrão de prompt reutilizável.

Esse quadro final recente demonstra um teste com mãos legíveis, geometria dos alimentos, vapor e iluminação prática — quatro detalhes dignos de verificação em todo o clipe gerado.

Consulte, armazene e revise o resultado

Após o envio, persista o taskId retornado antes de iniciar as consultas (polling). Use backoff exponencial com limite máximo, interrompa em caso de falha terminal e torne as consultas idempotentes, para que um worker reiniciado possa continuar a mesma tarefa. Se sua rota suportar um webhook, verifique sua assinatura ou segredo compartilhado antes de tratar a carga como confiável. O retorno de chamada (callback) deve atualizar o registro existente da tarefa, não criar uma segunda geração.

Em caso de SUCCESS, copie imediatamente o MP4. RunningHub informa que links de resultados gerados e links de upload podem expirar após 24 horas. Portanto, baixar o arquivo apenas quando um humano abrir a tela de revisão é inseguro. Armazene o arquivo, sua soma de verificação (checksum), o ID da tarefa do provedor, a versão do prompt, o manifesto de origem e o carimbo de data/hora da geração juntos. Em seguida, crie um poster e um proxy reproduzível no navegador somente se sua pilha de entrega exigir isso.

Clipe de movimento de café e vapor para revisão de movimentos sutis

Essa segunda saída real de movimento usa movimento contido das mãos, vapor ascendente e luz solar, oferecendo aos revisores uma superfície distinta de falha em comparação com a órbita do produto.

Revise o clipe completo, não apenas seu primeiro quadro. Avalie identidade, geometria de objetos, continuidade de movimento, trajetória da câmera, estabilidade do fundo, adequação do áudio e segurança na entrega. Uma tarefa tecnicamente bem-sucedida ainda pode ser inutilizável. Para campanhas com diversos modelos ou provedores, o fluxo de trabalho de vídeo IA com múltiplos modelos mostra como manter um único padrão de revisão em todas as rotas.

Direção do tecido, formato das mãos, contato dos pés, estabilidade do horizonte e altura da câmera formam uma lista compacta de verificação para aceitação de um resultado com forte ênfase em movimento.

Corrija erros comuns da API RunningHub Seedance 2.0

Trate erros conforme sua fase no ciclo de vida. Um erro 401 ou 403 aponta para chave, região, associação ou permissão — não para o prompt. Uma requisição rejeitada antes da obtenção de um taskId geralmente indica que o endpoint, o ID do aplicativo, o tipo de conteúdo ou a estrutura do corpo estão incorretos. Uma tarefa enfileirada que nunca avança indica problema de fila ou timeout. Uma tarefa com status FAILED e detalhes de verificação de conteúdo exige um prompt ou referência mais seguro. Uma tarefa bem-sucedida com URL expirada indica falha de armazenamento.| Sintoma | Verifique primeiro | Ação corretiva | |---|---|---| | Não autorizado | Origem da chave e região base | Remova a substituição obsoleta de nó; gire a chave e teste novamente uma chamada mínima | | Mapeamento de nó inválido | Versão do fluxo de trabalho e IDs de nó | Exporte o grafo atual e atualize apenas os nós nomeados | | Falha na conversão de ativo | Nome da ranhura, tipo e acessibilidade da fonte | Teste uma única ranhura; use o fallback de upload direto documentado | | Tarefa permanece em fila | Intervalo de sondagem e fila da conta | Reduza a frequência de chamadas; não crie tarefas duplicadas automaticamente | | URL do resultado expirou | Evento de armazenamento durável | Execute novamente apenas se o arquivo original nunca tiver sido copiado | | Clipe está visualmente incorreto | Prompt e manifesto da fonte | Mantenha a API inalterada e revise apenas uma variável criativa |

Registre o código de status, o código de erro do provedor, o ID da tarefa, a versão do fluxo de trabalho e os nomes dos campos sanitizados. Nunca registre a chave de API nem URLs completas de mídia privada. Adicione uma chave de idempotência em seu próprio serviço, mesmo que a rota do provedor não a exponha; isso evita que uma nova tentativa do cliente resulte em cobrança dupla.

Se a integração estiver tecnicamente funcionando, mas a coordenação estiver se tornando um gargalo, use Seedance Agent para organizar referências, transformar um briefing em planos de cena, comparar saídas aprovadas e executar novamente apenas o estágio com falha. Essa é uma escolha no nível de produção, não um substituto para compreender a API subjacente.

Conclusão

Uma configuração durável da API RunningHub Seedance 2.0 é um ciclo de vida, não um único comando cURL bem-sucedido: escolha a aplicação de IA correta ou a rota ComfyUI, mantenha a chave fora do código, valide uma chamada mínima, mapeie ativos explicitamente, persista o taskId, reduza a frequência de chamadas durante a sondagem, copie imediatamente os resultados temporários e avalie o clipe completo contra uma lista de verificação escrita de aceitação. Uma vez estabilizados esses limites, adicione webhooks, entradas multimodais mais amplas, agendamento em lote e aprovação humana — sem ocultar falhas por trás de automação adicional. Para planejar referências e planos de cena antes que os créditos sejam gastos — e levar o trabalho aprovado por meio de revisões e reexecuções seletivas — inicie o projeto com Seedance Agent.