Configuración de la API RunningHub Seedance 2.0: clave, recursos y primera llamada

AI Overview

¿Cuál es la forma más rápida de configurar la API de RunningHub Seedance 2.0?

Cree una clave de API de RunningHub, seleccione la ruta exacta de la aplicación de IA o del modelo Seedance 2.0, envíe una solicitud mínima y, a continuación, sondee su campo taskId. Solo agregue cargas de archivos, webhooks y reintentos para producción tras el éxito de esa primera llamada.

¿Debo usar el flujo de trabajo AI App API o un flujo de trabajo ComfyUI?

Use el flujo de trabajo AI App API cuando necesite un contrato de entrada fijo y alojado. Use la ruta OpenAPI de ComfyUI cuando su equipo requiera mapeos de nodos visibles, grafos reutilizables, preparación de recursos o pasos de modelo que varíen entre proyectos.

¿Cómo funcionan los identificadores de recursos (Seedance 2.0 asset IDs) en RunningHub?

Los identificadores de recursos permiten que los nodos compatibles de Seedance 2.0 reutilicen referencias ya preparadas. La integración de ComfyUI acepta identificadores simples, valores con prefijo asset://, listas separadas por comas o una cadena JSON en formato de matriz; sin embargo, el nodo seleccionado sigue determinando las ranuras de entrada válidas.

¿Por qué debe copiarse inmediatamente la URL de una tarea completada?

RunningHub genera vínculos temporales para medios cargados y resultados generados. Mueva cada archivo MP4 y cada imagen fija (poster) aprobados a su propio almacenamiento duradero tan pronto como la tarea finalice correctamente; un ID de tarea almacenado no constituye un archivo permanente de medios.

Lo que necesita antes de su primera llamada

Una configuración confiable comienza con cuatro valores conocidos: la región de la API, una clave válida, el identificador exacto de la aplicación de IA o del modelo, y un destino de almacenamiento bajo su control. No copie un punto de conexión de un tutorial no relacionado asumiendo que su cuerpo es compatible. RunningHub expone varios estilos de llamada, y cada página de detalles de API publicada constituye el contrato formal para esa ruta. La guía general de la API de Seedance 2.0 explica el patrón asíncrono general; esta guía se centra exclusivamente en RunningHub.

Mantenga la clave fuera del control de versiones. Para la integración oficial de ComfyUI, el patrón documentado de variables de entorno es:

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

Use la URL base regional mostrada en su propia consola de RunningHub y en la documentación actual. Una clave de consumidor puede requerir una membresía elegible, mientras que las claves empresariales pueden tener reglas de acceso distintas. Trate la capacidad de ver un modelo en el catálogo y la capacidad de invocarlo con su clave como dos verificaciones independientes.

Antes de consumir créditos, defina un «disparo de aceptación» único: un sujeto, una acción, un movimiento de cámara, una duración y una proporción de entrega. Si duda sobre la viabilidad del propio indicador (prompt), pruébelo primero en el espacio de trabajo del modelo Seedance 2.0. Esto separa los problemas del indicador de los problemas de integración.

Use un marco visualmente simple para la primera llamada. Esta imagen recién generada facilita la inspección de siluetas, reflejos, movimiento del agua y estabilidad del fondo; no constituye una referencia de rendimiento oficial de RunningHub.

Elija la ruta adecuada de RunningHub

RunningHub ofrece dos caminos prácticos para esta tarea. La ruta de la aplicación de IA resulta útil cuando el proveedor ya ha empaquetado Seedance 2.0 en una aplicación estable con entradas nombradas. Envíe la solicitud a ese ID de aplicación y recibirá un taskId. La API de complemento OpenAPI de ComfyUI es preferible cuando el grafo mismo forma parte de su lógica de producción o cuando necesita los ayudantes de recursos (Seedance 2.0 asset helpers) que ofrece.

No combine rutas en su primera prueba. Una solicitud mínima a una aplicación de IA debe demostrar autenticación, identificación correcta de la aplicación, envío a la cola y recuperación del resultado. Una llamada mínima a ComfyUI debe demostrar que el flujo de trabajo exportado se ejecuta sin cambios antes de introducir sobrescrituras dinámicas de nodeInfoList.

El complemento oficial de RunningHub para ComfyUI puede leer la configuración desde un nodo de ajustes, variables de entorno o un archivo .env, teniendo prioridad los ajustes definidos en el nodo. Registre qué capa proporcionó la clave. De lo contrario, un compañero podría rotar el secreto del entorno mientras un valor antiguo del nodo siga prevaleciendo en silencio.

Una toma con muchas referencias debe mantener legibles a la persona, la vestimenta, el animal, el clima y la ubicación. La imagen es una salida ilustrativa reciente, no una comparación oficial entre modelos.

Configuración paso a paso de la API de RunningHub Seedance 2.0

Comience con un esqueleto de solicitud que exponga únicamente las variables que su servicio realmente controla. La documentación actual de aplicaciones de IA de RunningHub muestra un punto de conexión con forma /run/ai-app/{appId} y devuelve un objeto de tarea con estados como QUEUED, RUNNING, SUCCESS o FAILED. Use el ejemplo de solicitud generado en la página exacta de detalles de la API como fuente de verdad para los nombres de los 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(`Submit failed: ${response.status}`);
const task = await response.json();
```Para un flujo de trabajo ComfyUI, importe uno de los ejemplos coincidentes, conecte únicamente `RH OpenAPI Settings` si no está utilizando la configuración del entorno y ejecute el grafo con valores estáticos. Una vez que funcione, exponga solo los nodos cuyos valores deben variar: indicación (*prompt*), referencia, duración, relación de aspecto (*ratio*) u opciones de salida, y almacene esos identificadores de nodo junto con la versión del flujo de trabajo.

Las herramientas de activos Seedance 2.0 de RunningHub añaden otra opción. `real_person_mode=false` sigue la ruta de carga directa. Cuando se habilita, las ranuras locales seleccionadas de imagen o video pueden convertirse en activos antes de la solicitud al modelo. `conversion_slots` controla qué ranuras participan. Pruebe primero una sola imagen, ya que una carga útil de nueve imágenes y tres videos oculta qué asignación causó un fallo.

```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=Video vertical de órbita de producto para verificar un resultado recuperado de la API

Esta salida de movimiento reproducible de Seedance demuestra qué inspeccionar tras la recuperación: geometría estable del producto, movimiento controlado de cámara y fotograma limpio. No se presenta como una referencia comparativa (benchmark) de RunningHub.

Crear entradas que sobrevivan al límite de la API

La API no puede inferir cuál archivo es el primer fotograma, el último fotograma, una referencia de personaje o una referencia de estilo. Cree un manifiesto de entradas antes del envío. Almacene un nombre local, la suma de comprobación (checksum) de origen, el tipo MIME, la ranura prevista, el identificador de activo (si se creó) y la etiqueta de la indicación (prompt) que lo referencia. Esto resulta más útil que una carpeta de archivos denominados final-2.png.

{
  "shot": "kitchen-01",
  "references": [
    {"role": "first_frame", "assetId": "asset-example-01"},
    {"role": "style", "url": "https://your-storage.example/style.jpg"}
  ],
  "prompt": "Toma de seguimiento media; el chef sirve el plato; sube vapor; luz práctica cálida",
  "ratio": "16:9"
}

La integración documentada de ComfyUI acepta un identificador de activo, un valor asset://<asset_ID>, valores separados por comas o saltos de línea, o una cadena JSON en formato de matriz. Esa flexibilidad es conveniente, pero la coherencia es más segura: elija una única representación en su base de código y valídelo antes de ejecutar el grafo. Para la conversión de imagen a video, la integración identifica first_frame y last_frame; los nodos de video multimodal pueden exponer múltiples ranuras de imagen y video. Use el espacio de trabajo de referencia a video para perfeccionar un paquete de referencias antes de automatizarlo.

Redacte las indicaciones (prompts) como instrucciones ejecutables de toma. Separe encuadre, sujeto, acción, entorno, iluminación y sonido. Si la primera llamada falla creativamente, simplifique un solo canal en lugar de modificar simultáneamente el punto final, los activos, la indicación (prompt) y el flujo de trabajo. El flujo de trabajo de indicaciones para imagen a video proporciona un patrón reutilizable de indicaciones (prompts).

Este fotograma final recién generado demuestra una prueba con manos legibles, geometría de los alimentos, vapor y iluminación práctica: cuatro detalles dignos de verificación a lo largo del clip generado.

Consultar, almacenar y revisar el resultado

Tras el envío, conserve inmediatamente el taskId devuelto antes de comenzar las consultas (polling). Use retroceso exponencial con límite superior, deténgase ante un fallo terminal y haga que las consultas (polling) sean idempotentes, de modo que un trabajador reiniciado pueda continuar con la misma tarea. Si su ruta admite un webhook, verifique su firma o secreto compartido antes de considerar la carga útil como de confianza. La devolución de llamada (callback) debe actualizar el registro de la tarea existente, no crear una segunda generación.

Al alcanzarse el estado SUCCESS, copie inmediatamente el archivo MP4. RunningHub indica que los enlaces a resultados generados y los enlaces de carga pueden expirar tras 24 horas. Por tanto, descargar únicamente cuando un humano abre una pantalla de revisión es inseguro. Almacene conjuntamente el archivo, su suma de comprobación (checksum), el identificador de tarea del proveedor, la versión de la indicación (prompt), el manifiesto de origen y la marca de tiempo de generación. Luego cree una imagen fija (poster) y un proxy reproducible en navegador únicamente si su pila de entrega lo requiere.

Clip de movimiento de café y vapor para revisar movimientos sutiles

Esta segunda salida real de movimiento emplea un movimiento restringido de manos, vapor ascendente y luz solar, ofreciendo a los revisores una superficie distinta de fallo respecto a la órbita del producto.

Revise el clip completo, no solo su primer fotograma. Evalúe identidad, geometría de objetos, continuidad del movimiento, trayectoria de la cámara, estabilidad del fondo, adecuación del audio y seguridad en la entrega. Una tarea técnicamente exitosa aún puede ser inutilizable. Para campañas con varios modelos o proveedores, el flujo de trabajo de video por IA con múltiples modelos muestra cómo mantener un mismo estándar de revisión en distintas rutas.

La dirección de la tela, la forma de las manos, el contacto de los pies, la estabilidad del horizonte y la altura de la cámara conforman una lista compacta de verificación para aceptar un resultado con mucho movimiento.

Corregir errores comunes de la API de RunningHub Seedance 2.0

Trate los errores según su etapa en el ciclo de vida. Un error 401 o 403 apunta a la clave, región, membresía o permisos, no a la indicación (prompt). Una solicitud rechazada antes de obtener un taskId suele significar que el punto final, el identificador de aplicación, el tipo de contenido o la estructura del cuerpo son incorrectos. Una tarea en cola que nunca avanza indica un problema de cola o de tiempo de espera (timeout). Una tarea con estado FAILED que incluye detalles de verificación de contenido requiere una indicación (prompt) o referencia más segura. Una tarea exitosa con una URL expirada indica un fallo de almacenamiento.| Síntoma | Verificar primero | Acción correctiva | |---|---|---| | No autorizado | Origen de la clave y región base | Eliminar la invalidación obsoleta del nodo; rotar la clave y probar nuevamente una llamada mínima | | Asignación de nodo no válida | Versión del flujo de trabajo e identificadores de nodo | Exportar el grafo actual y actualizar únicamente los nodos nombrados | | Conversión de activo fallida | Nombre de ranura, tipo y accesibilidad de la fuente | Probar una sola ranura; usar la alternativa documentada de carga directa | | Tarea sigue en cola | Intervalo de sondeo y cola de la cuenta | Reducir la frecuencia de solicitudes; no crear automáticamente trabajos duplicados | | URL del resultado expirada | Evento de almacenamiento duradero | Volver a ejecutar únicamente si el archivo original nunca se copió | | Clip visualmente incorrecto | Prompt y manifiesto de origen | Mantener la API sin cambios y revisar una única variable creativa |

Registrar el código de estado, el código de error del proveedor, el ID de la tarea, la versión del flujo de trabajo y los nombres de campo depurados. Nunca registrar la clave API ni las URLs completas de medios privados. Agregar una clave de idempotencia en su propio servicio, incluso si la ruta del proveedor no la expone; esto evita que un reintento del cliente genere un doble cargo.

Si la integración funciona técnicamente pero la coordinación se convierte en el cuello de botella, use Seedance Agent para organizar referencias, transformar un briefing en planos, comparar resultados aprobados y volver a ejecutar únicamente la etapa fallida. Esta es una decisión a nivel de producción, no un reemplazo para comprender la API subyacente.

Conclusión

Una configuración durable de la API RunningHub Seedance 2.0 es un ciclo de vida, no un simple comando cURL exitoso: seleccione la aplicación de IA adecuada o la ruta ComfyUI, mantenga la clave fuera del código, valide una llamada mínima, asigne explícitamente los activos, conserve persistentemente el taskId, reduzca la frecuencia de sondeos, copie inmediatamente los resultados temporales y evalúe el clip completo frente a una lista de verificación escrita de aceptación. Una vez que esos límites sean estables, agregue webhooks, entradas multimodales más amplias, programación por lotes y aprobación humana, sin ocultar fallos tras automatizaciones adicionales. Para planificar referencias y planos antes de gastar créditos —y llevar el trabajo aprobado a través de revisiones y reejecuciones selectivas— inicie el proyecto con Seedance Agent.