Skip to main content
Este documento presentará una forma de integración de la API de generación de videos SeeDance, que permite generar videos oficiales de SeeDance mediante la entrada de parámetros personalizados.

​
Proceso de solicitud

Para utilizar la API de generación de videos SeeDance, primero dirígete a la consola de Ace Data Cloud para obtener tu token de API y guardarlo para uso futuro. Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión; una vez completado, serás redirigido de nuevo a la página actual. Un token de API es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio. La primera solicitud incluirá un crédito gratuito para que puedas probarlo; si el crédito es insuficiente, puedes recargar el saldo general en la consola.
📘 Documentación completa: API de generación de videos SeeDance →

​
Uso básico

Primero, comprende la forma básica de uso, que consiste en ingresar la palabra clave content.text, el tipo content.type=text y el modelo model, para obtener el resultado procesado. El contenido específico es el siguiente:

Aquí podemos ver que hemos configurado los encabezados de la solicitud, que incluyen:
  • accept: el formato de respuesta que deseas recibir, aquí se establece como application/json, es decir, en formato JSON.
  • authorization: la clave para llamar a la API, que puedes seleccionar directamente después de solicitarla.
Además, se ha configurado el cuerpo de la solicitud, que incluye:
  • model: el modelo para generar el video.
    • Serie Seedance 1.x: doubao-seedance-1-0-pro-250528, doubao-seedance-1-0-pro-fast-251015, doubao-seedance-1-5-pro-251215, doubao-seedance-1-0-lite-t2v-250428, doubao-seedance-1-0-lite-i2v-250428.
    • Serie Seedance 2.0 (soporta referencias multimodales de personajes y audio/video): doubao-seedance-2-0-260128 (estándar), doubao-seedance-2-0-fast-260128 (rápido), doubao-seedance-2-0-mini-260615 (ligero).
    • Seedance 2.5: doubao-seedance-2-5-260628, soporta hasta 30 segundos, referencias de audio puro, más materiales, edición de video y extensión.
  • content: array de contenido de entrada, type puede ser text (palabra clave), image_url (imagen de referencia), audio_url (audio de referencia), video_url (video de referencia). Las imágenes pueden especificar su uso a través de role: first_frame (primer fotograma) / last_frame (último fotograma) / reference_image (referencia de personaje / sujeto).
  • resolution: resolución de salida, opciones 480p / 720p / 1080p / 4k. 2.5 soporta 480p, 720p, 1080p; 2.0 Fast/Mini soporta 480p, 720p; 2.0 Standard soporta hasta 4k.
  • ratio: relación de aspecto, opciones 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
  • duration: duración del video (segundos, entero). Serie 1.0 2–12; 1.5 Pro 4–12; serie 2.0 4–15; 2.5 de 4–30. 1.5/2.x soporta -1 (duración automática).
  • seed: semilla aleatoria, entero, -1 a 4294967295.
  • camerafixed: si la cámara está fija, true / false.
  • watermark: si se añade una marca de agua, true / false.
  • generate_audio: si se genera un video con audio, true / false, soportado por Seedance 1.5 Pro y la serie 2.x.
  • return_last_frame: si se devuelve la URL de la última imagen del video en el resultado.
  • omni_reference_task_type: solo 2.5; auto / reference / edit / extend.
  • output_format: solo 2.5; mp4 / mov, por defecto mp4.
  • tools: solo 2.5; actualmente soporta la herramienta de búsqueda en la web web_search, que puede limitar el número de resultados, el número de palabras clave y la fuente de búsqueda.
  • priority: 2.5 opción de prioridad de tarea, entero 0–9, por defecto 0.
  • safety_identifier: identificador de usuario final anónimo estable de hasta 64 caracteres; utiliza un hash o ID anónimo interno, no ingreses nombre, correo electrónico o número de teléfono.
  • execution_expires_after: tiempo de espera de la tarea (segundos), rango 3600–259200.
  • callback_url: dirección de callback asíncrono, al configurarla la API devolverá inmediatamente task_id, y cuando la tarea esté completa, enviará el resultado a esa dirección.
  • async: opcional, si se establece en true, la interfaz devolverá inmediatamente task_id, sin necesidad de proporcionar callback_url, y luego podrás obtener el resultado mediante la interfaz de consulta de tareas correspondiente.
Después de seleccionar, puedes ver que a la derecha también se ha generado el código correspondiente, como se muestra en la imagen:

Haz clic en el botón “Try” para realizar una prueba, como se muestra en la imagen anterior, y obtendremos el siguiente resultado:
El resultado devuelto tiene varios campos, que se describen a continuación:
  • success, el estado de la tarea de generación de video en este momento.
  • task_id, el ID de la tarea de generación de video en este momento.
  • trace_id, el ID de seguimiento de la generación de video en este momento.
  • data, la lista de resultados de la tarea de generación de video en este momento.
    • task_id, el ID del servidor de la tarea de generación de video en este momento.
    • video_url, el enlace del video de la tarea de generación de video en este momento.
    • status, el estado de la tarea de generación de video en este momento.
      • model, el modelo utilizado para generar el video.
Como podemos ver, hemos obtenido información satisfactoria sobre el video; solo necesitamos obtener el video generado de SeeDance a través de la dirección del enlace de video en data del resultado. Además, si deseas generar el código de integración correspondiente, puedes copiarlo directamente, por ejemplo, el código de CURL es el siguiente:

​
Descripción de parámetros en línea

En content[].text, se pueden pasar parámetros de generación al final del aviso mediante la adición de --parameter value (método antiguo, verificación débil, si se introduce incorrectamente se utilizarán valores predeterminados). La lista completa de parámetros es la siguiente:
Práctica recomendada: Utilizar directamente los campos de nivel superior correspondientes (como resolution, ratio, etc.) en el cuerpo de la solicitud, para un modo de verificación fuerte, si los parámetros se introducen incorrectamente, se devolverá un mensaje de error claro, lo que facilita la identificación de problemas.

​
Generación de video con audio

Seedance 1.5 Pro y la serie 2.x soportan la generación de videos con audio a través del parámetro generate_audio:
La serie 1.0 no soporta este parámetro.

​
Generación, edición y extensión multimodal de Seedance 2.5

doubao-seedance-2-5-260628 soporta 480p / 720p / 1080p, de 4 a 30 segundos o duración automática, y aumenta el límite de materiales a 30 imágenes de referencia, 10 videos de referencia, 10 audios de referencia (un total de hasta 50). La versión 2.5 también permite enviar solo audio de referencia, sin necesidad de proporcionar imágenes o videos al mismo tiempo. La generación multimodal normal puede omitir omni_reference_task_type, configurándolo como auto, o establecerlo explícitamente como reference. La edición y extensión de video deben incluir reference_video:
  • reference: Debe incluir al menos una reference_image, reference_video o reference_audio; la versión 2.5 soporta solo audio de referencia.
  • edit: Debe usar ratio: adaptive y duration: -1; la duración de salida se cobrará según el resultado real.
  • extend: Debe usar ratio: adaptive; duration puede ser de 4 a 30 o -1.
  • auto: El modelo selecciona automáticamente generación, edición o extensión según el aviso y los materiales.
  • Si el tipo de tarea no coincide con los materiales o el aviso, la tarea fallará y devolverá un error de parámetro localizable; ajuste según las restricciones anteriores y vuelva a enviar.

​
Primer fotograma de video generado a partir de imagen

Si desea generar un video a partir de una imagen, primero el parámetro content debe incluir un elemento de tipo image_url, el campo image_url debe estar en formato de objeto: {"url": "https://..."} o en formato Base64 {"url": "data:image/png;base64,..."}.
Nota: image_url no admite la entrada directa en formato de cadena (como "image_url": "https://cdn.acedata.cloud/e724d7f13d.png"), debe utilizar el formato de objeto "image_url": {"url": "https://..."}, de lo contrario, se devolverá un error 400.
Código correspondiente:
Al hacer clic en ejecutar, se puede ver que se obtiene un resultado inmediato, como el siguiente:
Se puede ver que el efecto generado es un video creado a partir de una imagen, el resultado es similar al mencionado anteriormente.

​
Primer y último fotograma de video generado a partir de imagen

Si desea generar el primer y último fotograma de un video a partir de una imagen, primero el parámetro content debe incluir un tipo image_url, y debe establecerse role como first_frame y last_frame, para poder especificar el siguiente contenido:
  • role: Especifica el primer fotograma o el último fotograma.
  • image_url
    • url Enlace de la imagen Al mismo tiempo, content también necesita incluir un tipo text como aviso.
Código correspondiente:
Al hacer clic en ejecutar, se puede ver que se obtiene un resultado inmediato, como se muestra a continuación:
Se puede ver que el efecto generado es un video de personaje, y el resultado es similar al anterior.

​
Referencia multimodal de personajes y audio y video (Seedance 2.0)

La serie Seedance 2.0 (doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128, doubao-seedance-2-0-mini-260615) admite reference_image, reference_audio y reference_video. Se pueden utilizar materiales propios o autorizados para mantener la consistencia en la identidad del personaje, el sujeto, la acción, el movimiento de cámara, el sonido y el ritmo.
Por favor, suba únicamente materiales de personas reales y personajes que sean propios o autorizados. Diferentes modelos tienen diferentes formas de soporte para materiales de personas reales; el formato de solicitud se mantiene sin cambios, si el material no cumple con los requisitos, se devolverá un error claro.
Puntos clave de uso:
  • Solo los modelos de la serie Seedance 2.0 admiten reference_image; los modelos 1.x deben usar first_frame / last_frame (primer y último fotograma de video generado a partir de imagen).
  • El primer fotograma de video generado a partir de imagen, el primer y último fotograma de video generado a partir de imagen y la referencia multimodal son tres escenarios mutuamente excluyentes: first_frame / last_frame no se pueden mezclar con reference_image / reference_video / reference_audio.
  • Si desea especificar los fotogramas inicial y final en la referencia multimodal, debe etiquetar la imagen como reference_image y mencionar en el texto “imagen 1 como fotograma inicial” o “imagen 2 como fotograma final”; si necesita bloquear estrictamente los fotogramas inicial y final, use solo first_frame / last_frame.
  • Límite máximo de cantidad de referencias multimodales: image_url hasta 9 imágenes; 2.0 también admite audio_url (role como reference_audio, hasta 3) y video_url (role como reference_video, hasta 3).
  • Requisitos para materiales de audio de referencia (audio_url): formato wav / mp3; duración de una sola pista de 2 a 15 segundos, hasta 3 pistas y duración total no superior a 15 segundos; cada pista no debe exceder 15 MB. Superar el rango de duración fallará en la fase de procesamiento del material.
  • Requisitos para materiales de video de referencia (video_url): formato mp4 / mov; duración de una sola pista de 2 a 15 segundos, hasta 3 pistas y duración total no superior a 15 segundos.
  • Se recomienda usar fotos de una sola persona, de frente, claras y sin obstrucciones; cuanto más clara sea la cara, mayor será la similitud.

​
Ejemplo 1: Primer plano manteniendo la apariencia del personaje

Se pasa una foto de un rostro, haciendo que la persona sonría y agite la mano hacia la cámara. El código correspondiente es:
El resultado devuelto es el siguiente, el video generado mantiene la apariencia del personaje con la foto de referencia:

​
Ejemplo 2: Colocar a la misma persona en un nuevo escenario

La gran ventaja de reference_image es que solo se conserva la identidad del personaje, mientras que el escenario, la vestimenta y la acción son completamente determinados por el texto. A continuación, con la misma foto de rostro, se hace que la persona vista un abrigo beige y camine por un parque otoñal:
El resultado devuelto es el siguiente, la apariencia del personaje se mantiene, mientras que el escenario ha cambiado a un parque otoñal:
💡 Si desea que el personaje reproduzca con precisión la composición de la foto (en lugar de “la misma persona en un escenario diferente”), puede usar first_frame (la primera imagen del video) para que el video comience a moverse desde esta foto.

​
Callback asíncrono

Debido a que la API de generación de videos de SeeDance tiene un tiempo de generación prolongado (aproximadamente 1-2 minutos), puede utilizar el campo callback_url para emplear el modo asíncrono, evitando que la conexión HTTP esté ocupada durante mucho tiempo. Flujo general: cuando el cliente inicia la solicitud especificando callback_url, la API devuelve inmediatamente una respuesta que incluye task_id; una vez que la tarea se completa, la plataforma enviará los resultados generados en formato JSON POST a callback_url, y los resultados también incluirán task_id para facilitar la asociación.
Cuando la tarea se completa, el contenido que la plataforma envía a callback_url es el siguiente:
El campo task_id en los resultados es el mismo que el devuelto al realizar la solicitud, y a través de este campo se puede realizar la asociación de la tarea.

​
Manejo de errores

Al llamar a la API, si se encuentra con un error, la API devolverá el código de error correspondiente y la información. Por ejemplo:
  • 400 token_mismatched: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
  • 400 api_not_implemented: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
  • 401 invalid_token: No autorizado, token de autorización inválido o faltante.
  • 429 too_many_requests: Demasiadas solicitudes, ha superado el límite de tasa.
  • 500 api_error: Error interno del servidor, algo salió mal en el servidor.

​
Ejemplo de respuesta de error

​
Conclusión

A través de este documento, ha aprendido cómo utilizar la API de generación de videos de Seedance para generar videos a partir de texto, imágenes de inicio y fin, y referencias multimodales, así como usar Seedance 2.5 para editar o extender videos. Esperamos que este documento le ayude a completar la integración de la API; si tiene alguna pregunta, comuníquese con el soporte técnico.