API de Wan 3.0 Video Prime

Use wan3.0-video-prime a través de la API de video asíncrona de APIMaster. La integración actual ofrece 480P / 720P / 1080P, 2–30 segundos enteros y un video por tarea. Revisión de parámetros e integración: 2026-10-26.

Endpoints y autenticación

Operación	Método y URL
Crear	POST https://apimaster.ai/v1/videos
Consultar	GET https://apimaster.ai/v1/videos/{task_id}
Descargar	GET https://apimaster.ai/v1/videos/{task_id}/content

Use Authorization: Bearer YOUR_API_KEY en cada solicitud y Content-Type: application/json al crear una tarea. Use una clave de API de APIMaster, no una clave de Alibaba Cloud. APIMaster proporciona la cabecera asíncrona del proveedor upstream; no necesita X-DashScope-Async.

El endpoint de creación compatible /videos/generations devuelve una estructura de respuesta diferente; los ejemplos siguientes usan sistemáticamente /videos.

Capacidades actuales de las rutas

Actualmente dos integraciones sirven este modelo: la ruta nativa de Alibaba Cloud y la ruta GMI. Los campos avanzados requieren la ruta correspondiente; enviar un campo no selecciona esa ruta. Confirme a qué ruta puede acceder su clave de API antes de usar ejemplos específicos de una ruta.

Capacidad	Nativa de Alibaba Cloud	GMI
Texto a video, primer fotograma, primer/último fotograma, imágenes de referencia	Integrado	Integrado, con campos de medios diferentes
Audio de referencia	metadata.input.media	audio_url
Documento / página web pública	Los campos de medios nativos se reenvían; no están cubiertos por la comprobación de generación completada	No compatible
Video de referencia, edición, extensión	Bloqueado antes del envío	No compatible
Duración automática -1	Bloqueado	Bloqueado
Relación de aspecto 21:9	Aceptado	Rechazado
Interruptor de audio explícito	generate_audio / audio	No compatible; omita estos campos
Desactivar la reescritura del prompt / semilla fija 0	La serialización actual no conserva prompt_extend: false ni seed: 0; no dependa de ellos	Los valores explícitos false y 0 se conservan

Un video silencioso de 5 segundos en 720P por la ruta nativa se completó, descargó y decodificó correctamente en la prueba de aceptación del 2026-10-24. Otras combinaciones de medios se describen a partir del adaptador y del contrato oficial, en lugar de presentarse como combinaciones probadas en generación. La disponibilidad y los precios de las rutas pueden cambiar; consulte la ficha del modelo.

Parámetros de solicitud comunes completos

Envíe estos campos en el nivel superior. Para la máxima compatibilidad, use duration, resolution y aspect_ratio explícitos, un prompt no vacío de como máximo 5,000 caracteres y omita las opciones específicas de cada ruta.

Campo	Tipo	Obligatorio / predeterminado	Comportamiento de APIMaster
model	string	Obligatorio	Exactamente wan3.0-video-prime
prompt	string	Obligatorio en ambas rutas	No vacío, incluso para la generación de imágenes. GMI valida 1–5,000 caracteres; el adaptador nativo requiere texto no vacío. El límite nativo oficial es 20,000; evite depender de ese límite superior entre rutas
duration	integer	5	2–30 segundos; sin -1, fracciones ni duración automática
seconds	string	Opcional	Alias de cadena, p. ej. "5"; debe coincidir con duration cuando se proporcionen ambos
resolution	string	720P	480P, 720P, 1080P; los valores en minúsculas de nivel superior se normalizan. Este valor predeterminado de APIMaster difiere del predeterminado nativo oficial
aspect_ratio	string	16:9	Valores comunes: adaptive, 16:9, 9:16, 1:1, 4:3, 3:4. 21:9 solo en la ruta nativa
ratio	string	Opcional	Alias de aspect_ratio; use un solo campo y no envíe valores en conflicto
size	string	Opcional	Alias de dimensiones como 1280x720; se aplica la validación específica de la ruta. Prefiera resolution y aspect_ratio. GMI requiere que el lado más corto coincida con el nivel de resolución; la ruta nativa solo acepta sus asignaciones de dimensiones compatibles
input_reference	string	Opcional	URL de imagen del primer fotograma. Use una URL HTTP(S) descargable públicamente para compatibilidad entre rutas; no la combine con otras entradas de primer fotograma
prompt_extend	boolean	Nativo true; GMI deja el valor predeterminado del proveedor cuando se omite	Reescritura del prompt. Actualmente la ruta nativa no puede desactivarla de forma fiable con false; GMI reenvía un booleano explícito
watermark	boolean	Predeterminado nativo oficial false; GMI deja el valor predeterminado del proveedor cuando se omite	Interruptor de marca de agua
seed	integer	Aleatoria cuando se omite	Rango fijo portable: 1–2147483647. La ruta nativa también acepta -1 para aleatorio; el 0 nativo se omite durante la serialización. GMI acepta 0–2147483647 y rechaza -1. Una semilla fija no garantiza una salida idéntica

Los alias de dimensiones nativos son 832x480, 480x832, 1280x720, 720x1280, 1920x1080 y 1080x1920 para los casos habituales de horizontal/vertical. Algunas asignaciones de dimensiones cuadradas se reducen a 1:1; otras dimensiones asignadas aún pueden fallar la validación de relación de aspecto. No use size para solicitar dimensiones arbitrarias.

Tablas de parámetros específicos de cada ruta

Campos de GMI

Estos son campos de nivel superior adicionales a la tabla común. El adaptador de GMI rechaza campos no reconocidos, incluidos metadata, images, image_urls, audio, generate_audio, video_urls y reference_video.

Campo	Tipo	Obligatorio / predeterminado	Comportamiento
negative_prompt	string	Opcional	Como máximo 500 caracteres
first_frame	string	Opcional	URL de imagen HTTP(S) pública; alternativa a input_reference
last_frame	string	Opcional	URL de imagen HTTP(S) pública del último fotograma; proporcione también un primer fotograma
reference_image	string o string[]	Opcional	1–10 URL de imágenes de referencia HTTP(S) públicas; use un arreglo para varias imágenes
audio_url	string	Opcional	URL de audio de referencia HTTP(S) pública; sujeta a la validación de medios del proveedor

Use controles de fotogramas o imágenes de referencia en una misma solicitud, no ambos. metadata.input.media nativo no se traduce a estos campos en GMI.

Campos nativos de Alibaba Cloud

Las entradas estructuradas nativas pertenecen dentro de metadata. Enviar objetos oficiales input o parameters directamente en el nivel superior no forma parte del contrato de APIMaster. Conserve siempre el prompt obligatorio de nivel superior.

Campo	Tipo	Obligatorio / predeterminado	Comportamiento
generate_audio	boolean	Predeterminado nativo oficial true	Si la salida contiene una pista de audio; false se conserva
audio	boolean	Opcional	Alias de generate_audio; proporcione solo uno
images	string[]	Opcional	Se convierten en entradas de medios reference_image; no son fotogramas primero/último ordenados. No los combine con input_reference
metadata	object	Opcional	Envuelve input y parameters nativos; no puede cambiar model
metadata.input	object	Opcional	Contenedor de entrada nativo
metadata.input.prompt	string	Opcional	Anulación del prompt nativo; prefiera el prompt de nivel superior únicamente
metadata.input.media	object[]	Opcional	Colección de medios nativa, con type y url en cada elemento
metadata.input.media[].type	string	Obligatorio por elemento	first_frame, last_frame, reference_image, reference_audio, file, link; reference_video actualmente se rechaza
metadata.input.media[].url	string	Obligatorio por elemento	Ubicación del medio; se recomiendan URL HTTP(S) públicas. Las URL temporales de OSS oficiales requieren un contexto de carga upstream válido por separado; APIMaster no proporciona ese contexto de carga
metadata.parameters	object	Opcional	Contenedor de parámetros nativo; no debe ser null
metadata.parameters.resolution	string	720P	480P, 720P, 1080P en mayúsculas
metadata.parameters.ratio	string	16:9	Relaciones de aspecto nativas, incluidas adaptive y 21:9
metadata.parameters.duration	integer	5	2–30; sin -1
metadata.parameters.audio	boolean	Predeterminado nativo oficial true	Interruptor de audio de salida
metadata.parameters.prompt_extend	boolean	true	Debe permanecer en true para file / link; el false explícito tiene la limitación de serialización indicada arriba
metadata.parameters.watermark	boolean	Predeterminado nativo oficial false	Interruptor de marca de agua
metadata.parameters.seed	integer	Aleatoria	-1 o 0–2147483647; el 0 tiene la limitación de serialización indicada arriba

Las opciones nativas de nivel superior anulan sus parámetros de metadata correspondientes. El input_reference de nivel superior reemplaza el arreglo de medios nativo; images añade entradas de imágenes de referencia cuando input_reference está ausente. Use un solo estilo de entrada y un solo estilo de parámetros para evitar anulaciones accidentales. No use img_url, first_frame_url, last_frame_url ni audio_url heredados dentro del input nativo; el adaptador rechaza esos campos de medios heredados para Wan 3.0.

Restricciones de medios

Las reglas oficiales de medios nativos que se indican a continuación también explican la validación del lado del proveedor; que un adaptador acepte una URL no demuestra que el medio sea válido.

Medio	Límites / notas de integración
Primer / último fotograma	Como máximo uno de cada uno; un último fotograma requiere un primer fotograma. No mezcle controles de fotogramas con reference_image
Imágenes de referencia	Como máximo 10; JPEG/JPG, PNG sin transparencia, BMP o WEBP; cada lado 240–8,000 px, relación de aspecto como máximo 8:1, como máximo 20 MB por imagen
Audio de referencia	Nativo: como máximo 5, WAV/MP3, cada uno de 1–15 segundos, combinados como máximo 15 segundos, como máximo 15 MB por archivo. GMI expone un único audio_url
Archivo / página web	Solo nativo: como máximo un archivo o una página legible públicamente; no combine file y link. Formatos de archivo oficiales: DOCX, DOC, XLSX, XLS, PPTX, PPT, PDF, TXT, KEY, PAGES, NUMBERS, MD; como máximo 100 MB, con un límite de 50 páginas para los formatos paginados aplicables. Mantenga prompt_extend: true
Video de referencia	Disponible oficialmente, pero actualmente bloqueado por la validación de facturación nativa de APIMaster; no expuesto en GMI. No use aquí los ejemplos de edición o extensión de video de la API oficial

El límite oficial nativo de medios combinados es de 20 elementos; los límites individuales y de combinación siguen aplicándose. Las URL de datos Base64 de imágenes forman parte del formato de entrada nativo oficial, pero la validación de URL de GMI no las acepta. Prefiera URL HTTP(S) descargables en todas las rutas.

Ejemplos

Texto a video, campos comunes

curl "https://apimaster.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"wan3.0-video-prime","prompt":"A paper boat drifting across a quiet pond at sunrise, gentle camera movement.","duration":5,"resolution":"720P","aspect_ratio":"16:9"}'

Primer fotograma, campos comunes

{"model":"wan3.0-video-prime","prompt":"The boat moves slowly forward, with soft ripples.","input_reference":"https://example.com/boat.png","duration":5,"resolution":"720P","aspect_ratio":"16:9"}

Primer / último fotograma en GMI

{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","first_frame":"https://example.com/start.png","last_frame":"https://example.com/end.png","duration":5,"resolution":"720P","prompt_extend":false,"seed":0}

Primer / último fotograma nativos y salida silenciosa

{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","duration":5,"resolution":"720P","generate_audio":false,"metadata":{"input":{"media":[{"type":"first_frame","url":"https://example.com/start.png"},{"type":"last_frame","url":"https://example.com/end.png"}]}}}

Imagen y audio de referencia nativos

{"model":"wan3.0-video-prime","prompt":"Animate the character in image 1, with the mood of audio 1.","duration":5,"resolution":"720P","metadata":{"input":{"media":[{"type":"reference_image","url":"https://example.com/character.png"},{"type":"reference_audio","url":"https://example.com/music.mp3"}]}}}

Reemplace las URL de medios de ejemplo por archivos públicos reales. Los ejemplos específicos de una ruta requieren la ruta correspondiente y siguen sujetos a las comprobaciones de combinación del proveedor upstream.

Respuesta, sondeo y descarga

La creación devuelve un ID de tarea de APIMaster, por ejemplo:

{"id":"task_example","task_id":"task_example","object":"video","model":"wan3.0-video-prime","status":"queued"}

Campo	Significado
id / task_id	Identificador de tarea de APIMaster, no un identificador de tarea upstream
status	queued, in_progress, completed, failed
progress	Progreso informado; no es una garantía de finalización
error.code / error.message	Detalles del fallo cuando corresponda
metadata.url	Dirección de contenido autenticada cuando se devuelve al completarse

Consulte cada 10–20 segundos con la misma clave de API hasta alcanzar un estado terminal; el éxito de la creación solo significa aceptación. La generación puede tardar varios minutos. Consulte una tarea aceptada en lugar de crear repetidamente tareas de pago.

curl "https://apimaster.ai/v1/videos/task_example" -H "Authorization: Bearer YOUR_API_KEY"
curl -L "https://apimaster.ai/v1/videos/task_example/content" \
  -H "Authorization: Bearer YOUR_API_KEY" -o wan-prime.mp4

Descargue y guarde el video completado cuanto antes; las URL de resultados del proveedor upstream pueden caducar. El sondeo repetido no genera otro cargo por generación.

Facturación y errores comunes

La facturación es por segundo a la resolución solicitada, con los precios de ruta/cuenta que se muestran en la ficha del modelo. El envío reserva el cargo estimado. La finalización nativa usa la duración facturable devuelta y el precio de envío congelado; GMI sigue el contrato de duración reservada. Las tareas fallidas liberan/reembolsan su reserva de generación. Desactivar el audio no implica una tarifa más económica. Use el registro de uso para conocer el importe final.

Error / síntoma	Acción
duration must be an integer from 2 to 30	Use un entero explícito; -1 no está integrado
unsupported Wan request field ...	Elimine un campo no compatible con GMI o confirme el acceso a la ruta nativa correspondiente
unsupported aspect ratio	Use una relación común; 21:9 requiere enrutamiento nativo
reference video requires an input-duration quote	Elimine el video de referencia; esta capacidad está actualmente bloqueada
prompt is required / fallo al obtener medios	Añada texto de nivel superior; use medios válidos y descargables públicamente
prompt_extend: false o seed: 0 no tiene efecto en la ruta nativa	Limitación de serialización actual; use una semilla positiva y no dependa de desactivar la reescritura

Fuentes: información oficial del modelo, referencia oficial de la API nativa y guía de uso oficial. Que una capacidad sea oficial no significa que el mismo campo esté expuesto en todas las rutas de APIMaster.