Wizstar Video API

Este documento está dirigido a desarrolladores que integran las capacidades de vídeo de Wizstar y abarca las API de Texto a vídeo, Imagen a vídeo, Traducción de vídeo, Sincronización labial, Imagen de producto a vídeo, Referencia de vídeo, Vídeo de humano digital, Consulta de avatares/voces, Consulta de tareas y más.

Todas las API Keys, los ID de recursos, la información de productos, los enlaces devueltos y otros datos similares de este documento son valores de ejemplo. Sustitúyelos por tus propios valores reales.

Instrucciones generales

Las siguientes convenciones se aplican a todas las API de este documento y no se repetirán en cada sección, salvo que se indique expresamente lo contrario.

Convenciones generales de las solicitudes

Elemento	Descripción
Autenticación	Todas las API requieren una API Key en la cabecera de la solicitud, con el formato Authorization: Bearer <YOUR_API_KEY>
Formato de la solicitud	Las API de envío de tareas usan application/json (POST); las API de consulta de tareas usan GET
Parámetros de archivo	Todos los campos de tipo archivo aceptan una cadena asset_id (generada previamente por el servicio de subida de recursos), no una subida binaria directa
Notificación de callback	Las API de tipo tarea admiten un parámetro opcional callback_url; el callback se activará cuando la tarea llegue a su estado final

Estructura general de la respuesta

La generación de vídeo es asíncrona. La API de envío devuelve inmediatamente un task_id, y puedes obtener el resultado final mediante la API de consulta de tareas o esperando al callback. El flujo general es: API de envío → Devuelve task_id → Consulta periódica a la API de consulta de tareas o espera al callback → Obtención del resultado del vídeo. Se recomienda un intervalo de consulta de ≥3 segundos para evitar el límite de frecuencia. El tiempo máximo de espera de la generación es de 24 horas; las tareas que superen este límite se considerarán fallidas y se reembolsarán.

Respuesta de envío de tarea correcta (igual en todas las API de envío):

JSON

{
  "errno": 0,
  "message": "success",
  "logid": "xxx",
  "timestamp": 1717401600,
  "data": {
    "tasks": [
      {
        "task_id": "oat_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "status": "success",
        "points_consumed": 10,
        "queue_position": 3,
        "estimated_wait_seconds": 120
      }
    ]
  }
}

Campo	Descripción
errno	0 indica éxito; para valores distintos de cero, consulta la sección Códigos de error
data[].task_id	ID de la tarea, con el prefijo oat_, que se usa en las consultas posteriores
data[].points_consumed	Créditos (uso) consumidos en esta llamada, para la conciliación de la facturación
data[].queue_position	Posición actual en la cola
data[].estimated_wait_seconds	Tiempo de espera estimado en segundos

Enumeración de estados de la tarea:

Estado	Descripción
asset_checking	Comprobación de control de riesgos del recurso en curso (sin cargo)
pending	Recurso listo, en cola a la espera de las condiciones de concurrencia/límite de frecuencia (sin cargo)
queued	Cobrado, a la espera de la generación
generating	Generando
completed	Todo correcto
failed	Fallido (rechazo por control de riesgos / saldo insuficiente / fallo de generación)

Códigos de error comunes

Código	Significado	Solución de problemas
30400201	Parámetro no válido	Comprueba los valores enumerados, la longitud, el rango y los requisitos condicionales de los parámetros
30400202	Se requiere un recurso	Falta el asset_id obligatorio
30400203	El tamaño del archivo supera el límite	El archivo del recurso supera el tamaño máximo permitido
30400204	Formato de archivo no compatible	El formato del archivo del recurso no es compatible
30400301	Créditos insuficientes	Saldo de créditos insuficiente; recarga y vuelve a intentarlo
30400302	Permisos insuficientes para esta función	Tu nivel de suscripción actual no da acceso a esta función
30400303	Límite de frecuencia superado	Se ha alcanzado el límite de frecuencia; reduce la frecuencia de las solicitudes y vuelve a intentarlo
30400304	Límite de tareas simultáneas superado	Se ha alcanzado el límite de tareas simultáneas; espera a que terminen las tareas en curso
30400401	Tarea no encontrada	El task_id no existe o no tienes permiso de acceso
30400402	Error al generar la tarea	Error al generar la tarea; vuelve a enviarla
30400601	Contenido rechazado por el control de riesgos	Contenido rechazado por el control de riesgos
30400602	El texto incluye contenido prohibido	El texto contiene contenido prohibido
30400603	El archivo incluye contenido prohibido	El archivo contiene contenido prohibido
30400901	Error interno del servidor	Error interno del servidor; vuelve a intentarlo más tarde o contacta con el soporte
20610101	Error en los parámetros de la solicitud de archivo	Error en los parámetros de la solicitud de archivo
10100001	Autenticación no válida o ausente	Autenticación no válida o inexistente
20610104	Cuota de almacenamiento superada	Cuota de almacenamiento insuficiente
20610103	Formato de archivo no compatible	Formato de archivo no admitido
10110002	Error interno del servidor	Error interno del servidor

Facturación y limitaciones generales

Elemento	Descripción
Modelo de facturación	Se cobra en créditos por tarea o por duración; consulta las tarifas concretas en la página de facturación de la consola. El cargo se aplica cuando el envío se realiza correctamente (queued)
Reembolso por fallo	Los créditos se reembolsan automáticamente si falla la generación
Bloqueo por control de riesgos / saldo	No se cobra nada si el control de riesgos rechaza la tarea o si el saldo es insuficiente
Referencia de recursos	Primero debes subir los archivos al servicio de recursos de archivo para obtener un asset_id; este servicio solo acepta referencias
Reintento del callback	Una respuesta 2xx se considera correcta

I. Gestión de recursos de archivo

Las imágenes, los vídeos y los audios que se usan en la generación de vídeo deben subirse primero al servicio de recursos de archivo para obtener un file_id (que hace de asset_id en las API de vídeo); después, se hace referencia a los archivos mediante asset_id.

1. Subir archivo

URL: POST https://wizstar.ai/wizstar/openapi/common/files/upload
Autenticación: Authorization: Bearer <YOUR_API_KEY> (igual que en las API de vídeo)
Formato de la solicitud: multipart/form-data

Campo	Obligatorio	Tipo	Descripción
file	Sí	file	Archivo que se va a subir.

Formatos admitidos:

Imagen: JPEG (.JPG/.JPEG), PNG
Vídeo: MP4, MOV
Audio: WAV, MP3

Lo anterior solo indica lo que admite la biblioteca de recursos; los requisitos reales dependen de las limitaciones de cada herramienta.

Respuesta de subida correcta:

JSON

{
  "errno": 0,
  "message": "success",
  "timestamp": 1782198346,
  "data": {
    "file_id": "2722637227394bc1b547bc4314777a25",
    "filename": "sample.jpeg",
    "content_type": "image/jpeg",
    "size_bytes": 205632,
    "status": 1,
    "expires_at": "2026-07-08T07:05:46Z"
  },
  "logid": "396982511",
  "lang": "en-US"
}

Límites de cuota:

Elemento	Límite
Máx. de archivos	500
Capacidad total	1 GB
Tamaño por archivo (imagen)	20 MB
Tamaño por archivo (vídeo)	200 MB
Tamaño por archivo (audio)	200 MB
Validez del archivo	15 días

Las cuotas anteriores pueden cambiar en cualquier momento, pero esto no afectará al periodo de validez de los archivos ya subidos, que se rige por el campo expires_at de la respuesta.

2. Consultar los metadatos de un archivo

URL: GET https://wizstar.ai/wizstar/openapi/common/files?file_id={file_id}
Autenticación: Authorization: Bearer <YOUR_API_KEY>

La estructura de la respuesta es la misma que la del campo data de la respuesta de subida correcta.

3. Listar los archivos del usuario

URL: GET https://wizstar.ai/wizstar/openapi/common/files
Autenticación: Authorization: Bearer <YOUR_API_KEY>

Parámetro	Tipo	Obligatorio	Descripción
limit	integer	No	Número máximo de elementos que se devuelven. Los valores superiores a 200 se reducen al valor predeterminado de 20. Rango válido: 1–200
cursor	string	No	Cursor de paginación, tomado del campo cursor de la respuesta de la página anterior
created_after	integer	No	Límite inferior de la fecha de creación (marca de tiempo Unix en milisegundos); 0 indica sin límite
created_before	integer	No	Límite superior de la fecha de creación (marca de tiempo Unix en milisegundos); 0 indica sin límite

La lista se ordena por fecha de creación en orden descendente. Solo devuelve archivos del usuario actual con status=1 que no hayan caducado ni se hayan eliminado.

Estructura de la respuesta:

JSON

{
  "errno": 0,
  "message": "success",
  "timestamp": 1782198015,
  "data": {
    "items": [
      {
        "file_id": "645230c9acfc43c59c1f1cec2f8156a2",
        "filename": "sample.jpeg",
        "content_type": "image/jpeg",
        "size_bytes": 205632,
        "status": 1,
        "expires_at": "2026-07-08T06:49:41Z"
      }
    ],
    "limit": 5,
    "cursor": "1782198346251_27226372...",
    "has_more": true
  },
  "logid": "396982756",
  "lang": "en-US"
}

Campo	Descripción
items	Lista de archivos
limit	Límite real de resultados aplicado por el servidor
cursor	Token de cursor para la página siguiente; si está vacío, es la última página
has_more	Indica si hay más datos disponibles; false indica que es la última página

4. Eliminar archivo

URL: DELETE https://wizstar.ai/wizstar/openapi/common/files?file_id={file_id}
Autenticación: Authorization: Bearer <YOUR_API_KEY>

5. Notas sobre la gestión de recursos de archivo

file_id es una cadena hexadecimal de 32 caracteres sin guiones. Se pasa como asset_id en las API de vídeo posteriores.
No se puede acceder a los archivos caducados y hay que volver a subirlos. Al consultar o eliminar un archivo caducado se devuelve errno 10110002.
Usa errno como único criterio para saber si una solicitud se ha realizado correctamente. El código de estado HTTP siempre es 200.
No incluyas una barra final en la URL: Consultar (GET), Listar (GET) y Eliminar (DELETE) no llevan barra final; Subir (POST /upload) sí lleva barra final.

II. Texto a vídeo

1. Descripción general

Genera un vídeo a partir de una indicación de texto. Adecuado cuando no tienes recursos previos y el resultado depende únicamente de la creatividad. Introduce el texto y los parámetros de generación para obtener uno o varios vídeos.

2. Solicitud básica y autenticación

URL: POST https://wizstar.com/wizstar/openapi/video/text-to-video
Autenticación: Authorization: Bearer <YOUR_API_KEY>

3. Parámetros de la solicitud

Campo	Obligatorio	Tipo	Descripción
prompt	Sí	string	Indicación de texto, ≤800 caracteres
model	Sí	string	Modelo de generación: seedance2.0 / seedance1.5 / kling
video_ratio	Sí	string	Relación de aspecto del vídeo: 9:16 / 16:9
video_duration	Sí	int	Duración del vídeo (segundos): 5 / 10
video_resolution	Sí	string	Resolución, p. ej. 720P
video_num	Sí	int	Número de vídeos que se generan: 1–4
callback_url	No	string	URL de callback para cuando se complete la tarea

4. Estructura de la respuesta

Devuelve la respuesta estándar de envío de tarea (consulta Instrucciones generales → Estructura general de la respuesta)

5. Ejemplo de código

cURL:

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/text-to-video' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "prompt": "Two puppies dancing on the grass, cinematic quality",
    "model": "seedance2.0",
    "video_ratio": "9:16",
    "video_duration": 5,
    "video_resolution": "720P",
    "video_num": 1
  }'

III. Imagen a vídeo

1. Descripción general

Usa una imagen como primer fotograma o referencia y la combina con una indicación de texto para generar un vídeo dinámico. Adecuado para dar vida a imágenes estáticas.

2. Solicitud básica y autenticación

URL: POST https://wizstar.com/wizstar/openapi/video/image-to-video
Autenticación: Authorization: Bearer <YOUR_API_KEY>

3. Parámetros de la solicitud

Campo	Obligatorio	Tipo	Descripción
image_asset_id	Sí	string	ID del recurso de imagen, JPG/PNG, ≤10MB
prompt	Sí	string	Indicación de texto, ≤800 caracteres
model	Sí	string	Modelo de generación: seedance2.0 / seedance1.5 / kling
video_ratio	Sí	string	Relación de aspecto del vídeo: 9:16 / 16:9
video_duration	Sí	int	Duración del vídeo (segundos): 5 / 10
video_resolution	Sí	string	Resolución: 720P
video_num	Sí	int	Número de vídeos que se generan: 1–4
callback_url	No	string	URL de callback

4. Estructura de la respuesta

Devuelve la respuesta estándar de envío de tarea (consulta Instrucciones generales → Estructura general de la respuesta).

5. Ejemplo de código

cURL:

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/image-to-video' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "image_asset_id": "<image_asset_id>",
    "prompt": "Camera slowly pulls back, clouds flowing in the sky, cinematic quality",
    "model": "seedance2.0",
    "video_ratio": "9:16",
    "video_duration": 5,
    "video_resolution": "720P",
    "video_num": 1
  }'

IV. Traducción de vídeo

1. Descripción general

Traduce un vídeo a un idioma de destino. Admite dos modos: lip_sync_audio (sincronización labial + doblaje) y audio_only (solo sustituye la pista de audio). Adecuado para localizar contenido en varios idiomas para mercados internacionales.

2. Solicitud básica y autenticación

URL: POST https://wizstar.com/wizstar/openapi/video/video-translate
Autenticación: Authorization: Bearer <YOUR_API_KEY>

3. Parámetros de la solicitud

Campo	Obligatorio	Tipo	Descripción
video_asset_id	Sí	string	ID del recurso de vídeo, ≤200MB, ≤5min
source_lang	Sí	string	Idioma de origen. Valores: auto / zh-CN / en-US
target_lang	Sí	string	Idioma de destino. Valores: en-US / es-ES / zh-CN / pt-PT / id-ID / de-DE / fr-FR / th-TH / vi-VN / ja-JP / ko-KR / ar-SA
translation_mode	Sí	string	Modo de traducción: lip_sync_audio / audio_only
callback_url	No	string	URL de callback

4. Estructura de la respuesta

Devuelve la respuesta estándar de envío de tarea (consulta Instrucciones generales → Estructura general de la respuesta).

5. Ejemplos de código

cURL (modo Lip Sync):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/video-translate' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "video_asset_id": "<video_asset_id>",
    "source_lang": "zh-CN",
    "target_lang": "en-US",
    "translation_mode": "lip_sync_audio"
  }'

cURL (modo solo audio):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/video-translate' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "video_asset_id": "<video_asset_id>",
    "source_lang": "zh-CN",
    "target_lang": "en-US",
    "translation_mode": "audio_only"
  }'

V. Sincronización labial

1. Descripción general

Hace que una persona de un vídeo o una imagen sincronice los labios con una locución. Como fuente de audio se admite audio subido o texto a voz (TTS). Admite 4 combinaciones: vídeo + audio subido, vídeo + TTS, imagen + audio subido, imagen + TTS.

2. Solicitud básica y autenticación

URL: POST https://wizstar.com/wizstar/openapi/video/lip-sync
Autenticación: Authorization: Bearer <YOUR_API_KEY>

3. Parámetros de la solicitud

Campo	Obligatorio	Tipo	Descripción
video_asset_id	Uno de los dos	string	ID del recurso de vídeo, ≤200MB, ≤5min (excluyente con image_asset_id)
image_asset_id	Uno de los dos	string	ID del recurso de imagen, JPG/PNG/WEBP, ≤10MB
audio_asset_id	Uno de los dos	string	ID del recurso de audio, MP3/WAV, ≥16kHz, ≤5min, ≤50MB (excluyente con script)
script	Uno de los dos	string	Texto para TTS, ≤1000 caracteres
voice_id	Condicional	string	Obligatorio si usas script; ID de la voz
prompt	Condicional	string	Obligatorio para la sincronización labial con imagen
video_ratio	Condicional	string	Relación de aspecto del vídeo: 9:16 / 16:9. Obligatorio para la sincronización labial con imagen
video_resolution	Condicional	string	Resolución: 720P. Obligatorio para la sincronización labial con imagen
callback_url	No	string	URL de callback

4. Estructura de la respuesta

Devuelve la respuesta estándar de envío de tarea (consulta Instrucciones generales → Estructura general de la respuesta).

5. Ejemplos de código

cURL (vídeo + audio subido):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/lip-sync' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "video_asset_id": "<video_asset_id>",
    "audio_asset_id": "<audio_asset_id>"
  }'

cURL (vídeo + audio TTS):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/lip-sync' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "video_asset_id": "<video_asset_id>",
    "script": "Hello everyone, welcome to our livestream.",
    "voice_id": "<voice_id>"
  }'

cURL (imagen + audio TTS):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/lip-sync' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "image_asset_id": "<image_asset_id>",
    "script": "Hello everyone, welcome to our livestream.",
    "voice_id": "<voice_id>",
    "prompt": "Generate a product introduction video based on the reference image",
    "video_ratio": "9:16",
    "video_resolution": "720P"
  }'

VI. Imagen de producto a vídeo

1. Descripción general

Genera vídeos cortos de marketing de producto o de compra a partir de la imagen principal del producto, las imágenes de detalle, las imágenes de escena y una indicación de texto.

2. Solicitud básica y autenticación

URL: POST https://wizstar.com/wizstar/openapi/video/product-to-video
Autenticación: Authorization: Bearer <YOUR_API_KEY>

3. Parámetros de la solicitud

Campo	Obligatorio	Tipo	Descripción
product_image_asset_id	Sí	string	ID del recurso de la imagen principal del producto, JPG/PNG
detail_image_asset_ids	No	string[]	Array de ID de recursos de imágenes de detalle, máx. 2 imágenes
scene_image_asset_ids	No	string[]	Array de ID de recursos de imágenes de escena, máx. 2 imágenes
prompt	Sí	string	Indicación de texto, ≤800 caracteres
model	Sí	string	Modelo de generación: kling
video_ratio	Sí	string	Relación de aspecto del vídeo: 9:16 / 16:9
video_duration	Sí	int	Duración del vídeo (segundos), valores: 5 / 10
video_resolution	Sí	string	Resolución: 720P
video_num	Sí	int	Número de vídeos que se generan: 1–4
callback_url	No	string	URL de callback

4. Estructura de la respuesta

Devuelve la respuesta estándar de envío de tarea (consulta Instrucciones generales → Estructura general de la respuesta).

5. Ejemplo de código

cURL:

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/product-to-video' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "product_image_asset_id": "<product_image_asset_id>",
    "detail_image_asset_ids": [],
    "scene_image_asset_ids": [],
    "prompt": "Show the product being used outdoors, highlighting portability",
    "model": "kling",
    "video_ratio": "9:16",
    "video_duration": 5,
    "video_resolution": "720P",
    "video_num": 1
  }'

VII. Referencia de vídeo

Genera un vídeo final a partir de la información del producto y un vídeo de referencia. Admite indicar un product_url, o bien información de producto personalizada + un vídeo de referencia subido por el usuario.

Referencia de vídeo - Generar

1. Descripción general

Genera un vídeo final a partir de un vídeo de referencia. Admite tres métodos: hacer referencia a resultados recomendados, pasar un product_url o usar un vídeo de referencia subido por el usuario.

2. Solicitud básica y autenticación

URL: POST https://wizstar.com/wizstar/openapi/video/reference/create
Autenticación: Authorization: Bearer <YOUR_API_KEY>

3. Parámetros de la solicitud

Campo	Obligatorio	Tipo	Descripción
product_url	Condicional	string	URL del producto (si se rellenan manualmente product_name, product_description y product_image_asset_ids, tienen prioridad los valores introducidos manualmente)
product_name	Condicional	string	Nombre del producto (para productos introducidos manualmente)
product_description	Condicional	string	Descripción del producto (para productos introducidos manualmente)
product_image_asset_ids	Condicional	string[]	Array de ID de recursos de imágenes del producto (para productos introducidos manualmente)
reference_video_asset_id	Sí	string	ID del recurso del vídeo de referencia
currency	No	string	Moneda: USD / GBP / AUD / CAD / SGD / CNY / TWD / HKD / MOP / EUR / MXN / BRL / IDR / THB / VND / JPY / KRW
target_language	Sí	string	Idioma de destino: en-US
prompt	Condicional	string	Indicación de generación, ≤800 caracteres
model	Sí	string	Modelo de generación: seedance2.0 / kling
video_ratio	Sí	string	Relación de aspecto del vídeo: 9:16 / 16:9
video_resolution	Sí	string	Resolución: 720P
original_price	No	string	Precio original del producto
promo_price	No	string	Precio promocional/con descuento
promo_description	No	string	Descripción de la promoción
callback_url	No	string	URL de callback

4. Estructura de la respuesta

Devuelve la respuesta estándar de envío de tarea (consulta Instrucciones generales → Estructura general de la respuesta).

5. Ejemplo de código

cURL (producto personalizado + vídeo de referencia subido por el usuario):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/reference/create' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "product_name": "Wireless Earbuds",
    "product_description": "High-quality wireless earbuds with active noise cancellation",
    "product_image_asset_ids": ["<product_image_asset_id>"],
    "currency": "USD",
    "reference_video_asset_id": "<reference_video_asset_id>",
    "target_language": "en-US",
    "model": "seedance2.0",
    "video_ratio": "9:16",
    "video_resolution": "720P"
  }'

VIII. Sincronización labial de imagen y vídeo

1. Descripción general

Indica una figura de humano digital y una voz, añade varios guiones y genera por lotes vídeos de humanos digitales hablando. Adecuado para producir varios vídeos hablados de una sola vez.

2. Solicitud básica y autenticación

URL: POST https://wizstar.com/wizstar/openapi/video/batch-broadcast
Autenticación: Authorization: Bearer <YOUR_API_KEY>

3. Parámetros de la solicitud

Campo	Obligatorio	Tipo	Descripción
figure_id	Sí	string	ID del humano digital
figure_source	Sí	int	Origen de la figura (p. ej., 2 representa un tipo de origen concreto)
voice_id	Sí	string	ID de la voz
script	Sí	string[]	Array de guiones, máx. 10 elementos, cada uno ≤1000 caracteres
speed	No	float	Velocidad del habla: 0.5–2.0
pitch	No	int	Tono: 1–3
screen_type	Sí	int	Tipo de pantalla: 1 (vertical) / 2 (horizontal)
language	No	string	Idioma: zh-CN / en-US / ja-JP / id-ID
video_resolution	No	string	Resolución: 1080P
callback_url	No	string	URL de callback

4. Estructura de la respuesta

Devuelve la respuesta estándar de envío de tarea (consulta Instrucciones generales → Estructura general de la respuesta).

5. Ejemplo de código

cURL:

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/batch-broadcast' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "figure_id": "<figure_id>",
    "figure_source": 2,
    "voice_id": "<voice_id>",
    "script": ["Hello everyone, welcome to our product showcase.", "Today we are introducing a brand new smart device."],
    "screen_type": 1,
    "language": "zh-CN"
  }'

IX. Lista de avatares

1. Descripción general

Consulta los avatares disponibles. Admite la galería pública de avatares (scope=public) y la galería privada del usuario (scope=private). Se puede filtrar por género y relación de aspecto (9:16 / 16:9).

2. Solicitud básica y autenticación

URL: POST https://wizstar.com/wizstar/openapi/video/figure/list
Autenticación: Authorization: Bearer <YOUR_API_KEY>

3. Parámetros de la solicitud

Campo	Obligatorio	Tipo	Descripción
scope	Sí	string	public (pública) / private (privada)
page_no	No	int	Número de página
page_size	No	int	Elementos por página, 100 por defecto
gender	No	int	Género: 0 (sin definir), 1 (masculino), 2 (femenino)
screen	No	int	Pantalla: 1 (vertical), 2 (horizontal)
race	No	int	Etnia: 1 (caucásica), 2 (asiática oriental), 3 (asiática meridional), 4 (latina), 5 (de Oriente Medio), 6 (africana)
target_audience	No	int	Edad: 1 (joven), 2 (mediana edad), 3 (mayor)

4. Estructura de la respuesta

Devuelve una lista paginada de avatares:

JSON

{
  "errno": 0,
  "message": "success",
  "logid": "xxx",
  "timestamp": 1717401600,
  "data": {
    "count": 30,
    "list": [
      {
        "figure_id": 10086,
        "name": "Business Man",
        "gender": 1,
        "cover": "https://cdn.example.com/figure/cover_10086.jpg",
        "figure_source": 2,
        "screen": 1,
        "target_audience": 1,
        "race": 1,
        "status": 1
      },
      {
        "figure_id": 10087,
        "name": "Sweet Girl",
        "gender": 0,
        "cover": "https://cdn.example.com/figure/cover_10087.jpg",
        "figure_source": 2,
        "screen": 2,
        "target_audience": 0,
        "race": 0,
        "status": 1
      }
    ]
  }
}

5. Ejemplos de código

cURL (galería pública de avatares):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/figure/list' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{"scope":"public","page_no":1,"page_size":16}'

cURL (galería privada de avatares con filtros):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/figure/list' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{"scope":"public","page_no":1,"page_size":16,"gender":2,"screen":1}'

X. Búsqueda de voces

1. Descripción general

Busca en la galería de voces. Admite voces públicas (scope=public) y voces privadas del usuario (scope=private). Se usa para elegir el voice_id en la sincronización labial, los vídeos de humanos digitales y otras API.

2. Solicitud básica y autenticación

URL: POST https://wizstar.com/wizstar/openapi/video/tts/search
Autenticación: Authorization: Bearer <YOUR_API_KEY>

3. Parámetros de la solicitud

Campo	Obligatorio	Tipo	Descripción
scope	Sí	string	public (pública) / private (privada)
pn	No	int	Número de página
rn	No	int	Elementos por página
name	No	string	Búsqueda aproximada por nombre
gender	No	int	Género: 0 (todos), 1 (masculino), 2 (femenino)
language	No	int	Idioma: 1 (inglés), 2 (chino), 3 (francés), 4 (alemán), 5 (español), 6 (tailandés), 7 (indonesio), 8 (portugués), 9 (japonés), 10 (coreano), 11 (vietnamita), 12 (árabe)
scene	No	int	Escena: 1 (vida cotidiana), 2 (e-commerce), 3 (publicidad/marketing), 4 (atención al cliente), 5 (presentación de noticias), 6 (divulgación científica)
age	No	int	Edad: 1 (joven), 2 (mediana edad), 3 (mayor)

4. Estructura de la respuesta

Devuelve una lista paginada de voces:

JSON

{
  "errno": 0,
  "message": "success",
  "logid": "xxx",
  "timestamp": 1717401600,
  "data": {
    "count": 50,
    "list": [
      {
        "media_id": 1001,
        "name": "Sweet Female Voice",
        "gender": 0,
        "language": 1,
        "scene": 1,
        "age": 1,
        "denoise": 0,
        "status": 1,
        "recommend": 1,
        "status_msg": "",
        "preview": "https://cdn.example.com/tts/preview_1001.mp3",
        "duration": 5000,
        "upload_url": "",
        "is_public": 1
      }
    ]
  }
}

Campo	Descripción
media_id	ID de la voz, que se usa como voice_id en otras API
name	Nombre de la voz
preview	Enlace al audio de muestra
is_public	1 (pública) / 0 (privada)

5. Ejemplos de código

cURL (voces públicas):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/tts/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "scope": "public",
    "pn": 1,
    "rn": 20,
    "name": "Sweet",
    "gender": 0
  }'

cURL (voces privadas):

bash

curl -X POST 'https://wizstar.com/wizstar/openapi/video/tts/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -d '{
    "scope": "private",
    "pn": 1,
    "rn": 20
  }'

XI. Consulta de tareas

1. Descripción general

Consulta el estado de la tarea y los resultados de la generación con el task_id que devuelve la API de envío. Todas las API de generación asíncrona usan este endpoint para obtener el vídeo final.

2. Solicitud básica y autenticación

URL: GET https://wizstar.com/wizstar/openapi/video/task
Autenticación: Authorization: Bearer <YOUR_API_KEY>

3. Parámetros de la solicitud (Query)

Campo	Obligatorio	Tipo	Valor predeterminado	Descripción
task_id	Sí	string	—	ID de la tarea, con el prefijo oat_

4. Estructura de la respuesta

JSON

{
  "errno": 0,
  "message": "success",
  "logid": "<log_id>",
  "timestamp": 1781183414,
  "lang": "zh-CN",
  "data": {
    "task_id": "oat_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "completed",
    "results": [
      {
        "video_url": "<video_url_without_watermark>",
        "watermark_video_url": "<video_url_with_watermark>",
        "cover_url": "<cover_image_url>",
        "watermark_cover_url": "<cover_image_url_with_watermark>",
        "duration": 5.04,
        "width": 720,
        "height": 1280
      }
    ],
    "error_code": "",
    "error_message": ""
  }
}

Campo	Descripción
status	Estado de la tarea; consulta Instrucciones generales → Enumeración de estados de la tarea
results	Array de resultados generados, un vídeo por elemento
results[].video_url	URL del vídeo sin marca de agua
results[].duration	Duración del vídeo (segundos)
error_code / error_message	Información del error en caso de fallo

5. Ejemplo de código

cURL:

bash

curl -X GET 'https://wizstar.com/wizstar/openapi/video/task?task_id=oat_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

XII. Notificación de callback

Si indicas un callback_url al enviar una tarea, la plataforma enviará un callback mediante POST a esa URL cuando la tarea llegue a un estado final (todo correcto o algún fallo).

1. Activación y reintentos

Condición de activación: se activa una sola vez cuando todos los subvídeos de la tarea llegan a un estado final (no se activa por cada vídeo).
Todo correcto → status=completed; algún fallo → status=failed

2. Ejemplo de payload del callback

JSON

{
  "task_id": "oat_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "results": [
    {
      "video_url": "https://xxx.com/path/to/video.mp4",
      "watermark_video_url": "https://xxx.com/path/to/video_wm.mp4",
      "cover_url": "https://xxx.com/path/to/cover.jpg",
      "watermark_cover_url": "https://xxx.com/path/to/cover_wm.jpg",
      "duration": 15.5,
      "width": 1920,
      "height": 1080
    }
  ],
  "error_code": "",
  "error_message": ""
}

3. Notas para el receptor

El receptor del callback debe devolver un estado 2xx en un plazo de 10 segundos; de lo contrario, se considerará un fallo y se reintentará.
Se recomienda implementar la idempotencia según el task_id para evitar procesar duplicados por los reintentos.
El callback es una notificación de respaldo; aun así, se recomienda mantener la posibilidad de consultar el estado de forma activa.