La API de PixVerse AI para convertir imágenes en vídeos utiliza identificadores distintos para una imagen subida y una tarea de generación de vídeo. Guarda el ID de la imagen, envía una solicitud de generación y, a continuación, comprueba periódicamente el ID del vídeo devuelto hasta que se complete o falle. Comprueba la configuración del modelo antes de añadir efectos o aumentar la cola.
Esta guía trata sobre la API de la plataforma PixVerse. Su funcionamiento es independiente de la interfaz de la aplicación para usuarios y de las ventajas de la suscripción.
Si quieres acceder a contenidos multimedia de personajes a través del navegador sin tener que desarrollar una integración con una API, El creador de Cherrypop te permite empezar con un personaje original y continuar en los medios de comunicación. El flujo de trabajo técnico que se describe a continuación responde a una necesidad diferente; no implica ninguna API compartida ni controles de proveedores coincidentes.
Asignar la solicitud de conversión de imagen a vídeo de PixVerse AI
De PixVerse Guía para convertir imágenes en vídeo describe cómo subir una imagen, crear una tarea de generación y comprobar su estado antes de descargarla. La subida proporciona un img_id; la respuesta de generación proporciona un video_id. Un identificador de rastreo es un tercer concepto que se utiliza en las solicitudes.
| Identificador | Significado en el flujo de trabajo | Error que hay que evitar |
|---|---|---|
| img_id | Imagen subida utilizada como entrada | Considerarlo como un vídeo terminado |
| video_id | Tarea de generación de vídeo para consultar | Sustituirla por una nueva tarea al realizar la consulta |
| Ai-trace-id | Solicitar el valor de seguimiento | Reutilizar una constante para cada solicitud única |
| template_id | Plantilla de efecto seleccionada opcional | Añadir un efecto sin querer a una línea de base |
Guarda estos valores en un registro de tareas persistente junto con el archivo de entrada, la línea de comandos, el modelo y la configuración. Al actualizar la página o reiniciar el trabajador, debería reanudarse el seguimiento de la misma tarea. Mantén las claves de API en la configuración del servidor y fuera del registro, del código del navegador y de los registros de diagnóstico.
Prepara primero una imagen normal
El subir referencia Enumera los formatos JPEG/JPG, PNG y WebP, un tamaño de archivo inferior a 20 MB y unas dimensiones máximas de 10 000 píxeles. La guía recomienda un tamaño mínimo de 1024 por 1024 píxeles y un motivo nítido; dicha recomendación no constituye un tamaño mínimo aceptado.
Para un briefing creativo inicial, utiliza una fotografía original de una campana de escritorio de latón. Pide que se realice un movimiento de cámara moderado mientras la campana permanece sobre la mesa. Esto proporciona a la revisión un contorno claro del objeto, una base estable y un cambio sencillo y deliberado.
Mantén la imagen original separada de cualquier miniatura de vista previa. Si una integración envía accidentalmente la miniatura, una subida correcta podría ocultar una entrada errónea. Guarda el identificador del recurso y una suma de comprobación no confidencial junto con el trabajo para que puedas confirmar qué se ha enviado realmente.
Para subir un archivo, envía los datos del formulario multiparte a POST /openapi/v2/image/upload en https://app-api.pixverse.ai, con el archivo en la carpeta imagen campo. La referencia también muestra un url_de_la_imagen opción. Facilita la documentación API-KEY y Ai-trace-id encabezados. Si se realiza correctamente, guardar Resp.img_id; la respuesta de la subida también incluye Resp.img_url.
Establecer una referencia básica para la conversión de imágenes a vídeo
Enviar JSON a POST /openapi/v2/video/img/generate en el mismo servidor de la API, utilizando esos encabezados además de Tipo de contenido: application/json. El Referencia de «imagen a vídeo» devoluciones Resp.video_id en un sobre que contiene Código de error y ErrMsg. Comprueba la respuesta HTTP y ese «envelope» antes de aceptar la tarea. Los ejemplos de éxito documentados utilizan Código de error: 0.
Empieza con la configuración más sencilla que exprese la tarea. Un ejemplo de indicación para la campana es: “La cámara se acerca lentamente a la campana de latón, mientras que esta permanece inmóvil sobre el escritorio”.”
El Página del modelo V6 concretiza la línea de base. Para la conversión de imagen a vídeo, requiere modelo: "v6", un número entero img_id, un indicación de un máximo de 5.000 caracteres, número entero duración de 1 a 15 segundos, y un calidad serie de 360p, 540p, 720p o 1080p. Una toma de cinco segundos a 720p con el «efecto campana» entra dentro de esos ajustes documentados. En este caso no se ha realizado.
V6: lista de opciones generar_audio_cambiar y generar_cambio_entre_varios_clips Valores booleanos. Configúralos deliberadamente cuando el audio o varios clips afecten al resumen. Su columna «Imagen a vídeo» no admite relación de aspecto, aunque la función «texto a vídeo» sí lo hace. No copies toda la configuración de «texto a vídeo» en este punto final.
Añade efectos solo cuando la transformación sea la tarea
De PixVerse Documentación sobre efectos de vídeo describe cómo seleccionar un efecto y añadir su ID de plantilla a los parámetros de generación. En el caso de las plantillas con varias imágenes, especifica img_ids, con el recuento requerido indicado en Effect Center. Una lista de imágenes es un formato de entrada distinto al de una sola img_id línea de referencia.
En cuanto a la campana del escritorio, decide si quieres una toma fiel del objeto o una transformación estilizada. Ambas pueden ser proyectos creativos válidos, pero deben tener criterios de aceptación diferentes. Una transformación que altere la campana no es un defecto si el objetivo del efecto es precisamente cambiarla.
Hay que prestar atención a los ejemplos: la guía de efectos utiliza v4.5, mientras que la referencia de generación utiliza v6. La referencia genérica también muestra campos de efectos de sonido independientes, mientras que los documentos de la versión 6 generar_audio_cambiar. Estos ejemplos no recogen todas las combinaciones posibles de plantillas y campos opcionales para la versión 6. Comprueba la configuración compatible con la plantilla seleccionada antes de combinarlas. Los ejemplos publicados también contienen comentarios o comas al final de las líneas; crea un JSON válido en lugar de pegarlos tal cual.
Haz que los efectos sean opcionales en tu aplicación. Mantén el ID de la plantilla en el resumen visible del trabajo, de modo que quien revise un resultado inesperado pueda ver si se solicitó la transformación.
Considera los resultados «pendiente», «completado» y «fallido» como resultados distintos
Uso GET /openapi/v2/video/result/{video_id} con el ID de la tarea guardada y los encabezados documentados. El referencia de estado devuelve el estado del trabajo en Estado de respuesta. Una respuesta positiva a la consulta de estado solo significa que la consulta se ha realizado correctamente; comprueba el estado anidado antes de mostrar un resultado.
Utiliza los estados documentados para determinar la siguiente acción:
| Estado de respuesta | Significado documentado | Acción de la aplicación |
|---|---|---|
| 1 | Generación exitosa | Lee Resp.url y recupera el archivo |
| 5 | En espera o en proceso de generación | Consultar el mismo «video_id» |
| 6 | Eliminado | Deja de consultar; muestra que la tarea se ha eliminado |
| 7 | La moderación ha fallado | Detener; mostrar un fallo evidente |
| 8 | Error en la generación | Detener; conservar los datos de diagnóstico para su revisión |
Mantén visibles los estados inesperados como «sin resolver». Solo el estado de éxito documentado debe desbloquear la ruta del resultado; no interpretes un número desconocido como una finalización. La ausencia de una URL de resultado debe dar lugar a una investigación, en lugar de a un botón de descarga.
El Guía de estados menciona tanto una frecuencia de sondeo de 3 a 5 segundos como intervalos de no menos de cinco segundos. Cinco segundos cumplen ambos requisitos. Añade un tiempo de espera de la aplicación y una ruta de reanudación posterior; el hecho de que se alcance el tiempo de espera no implica que la tarea del proveedor haya fallado.
Identifica la fase en la que se produce el fallo antes de volver a intentarlo
Separa los fallos de transporte, los errores de API, los estados de los trabajos en la terminal y los resultados creativos no deseados. Guarda la hora de la solicitud, el punto final, el ID de seguimiento, el modelo, el estado HTTP y los campos de error devueltos para que un informe de asistencia técnica pueda identificar el intento concreto.
- 400013 o 400017: La guía «De imagen a vídeo» detecta valores o parámetros de solicitud no válidos. Comprueba la sintaxis JSON, los tipos de valores, el ID de entrada y los campos admitidos por el modelo seleccionado antes de volver a enviar la solicitud.
- 500044: La guía establece un límite de concurrencia. Se suspenden los nuevos envíos hasta que finalicen los trabajos en curso. PixVerse’s página de limitación de velocidad define la concurrencia como la generación simultánea de tareas, por lo que aumentar el número de trabajadores no elimina el límite de cuentas.
- Queda una tarea pendiente: Asegúrate de que estás consultando el ID del vídeo guardado y de que utilizas ID de seguimiento distintos para cada solicitud. La guía señala que la reutilización de ID de seguimiento es un problema que requiere resolución; no establece una deduplicación automática.
- Se agota el tiempo de espera de una solicitud de creación: Es posible que se desconozca el resultado. Comprueba los registros de respuesta y los registros de la cuenta antes de autorizar una sustitución. Si no se ha recibido ningún ID de tarea, todavía no hay nada que introducir en la URL de estado.
Un fallo en la moderación es un resultado definitivo, no un desencadenante de intentos automáticos de eludir las medidas de seguridad. Un clip terminado que contenga movimientos no deseados requiere una revisión creativa, no el mismo tratamiento de reintento que se aplica a un error de conexión.
Presupuesto para la configuración de la API que has seleccionado
La guía oficial requiere un acceso adecuado a la API y créditos disponibles o adquiridos. Este artículo no garantiza que un plan para consumidores incluya el uso de la API, ni que una ventaja promocional mostrada se aplique al punto final y al modelo que hayas elegido.
Para cada lote, registra el coste de la configuración seleccionada y el número de resultados solicitados. Reserva presupuesto para un número reducido de correcciones explícitas, en lugar de un bucle de reintentos sin límite. Distingue en el registro entre los reintentos de transporte, las tareas fallidas y las alternativas creativas; cada uno de ellos responde a cuestiones diferentes sobre fiabilidad y coste.
Comprueba el uso real de la cuenta tras un periodo de prueba autorizado. Esta guía no especifica los cargos actuales, los derechos incluidos en los planes de consumo ni cómo se refleja un reembolso en una cuenta.
Comprueba el archivo y el resultado creativo
Descarga el resultado final y comprueba que se reproduce correctamente, que tiene el encuadre deseado y que se ajusta a los requisitos de duración del proyecto. A continuación, revisa el contorno de la campana, la base y el fondo en varios puntos. Una URL devuelta no es tan fiable como un archivo que hayas abierto, y un archivo reproducible no es tan fiable como un clip que cumpla con las especificaciones.
Guarda el resultado junto a su entrada y al registro de generación. El flujo de trabajo completado debe indicar qué imagen, modelo, ajustes y plantilla opcional han dado lugar a ese archivo. Antes de aumentar el tamaño del lote, comprueba que un trabajo se pueda recuperar tras un reinicio y que se pueda seguir su trayectoria hasta obtener un archivo reproducible.
Cuando prefieras crear con un personaje en lugar de...
Una integración mediante API resulta útil cuando necesitas gestionar envíos, registros de tareas y archivos en tu propia aplicación. Si tu objetivo inmediato es crear un personaje de compañía original, Cherrypop ofrece un flujo de trabajo en el navegador: define la apariencia, la personalidad y un escenario, y luego pasa a la creación de chats y contenidos multimedia compatibles.
El Vídeo de Cherrypop Incluye los modos «imagen a vídeo» y «continuación». Considéralo como una ruta alternativa, no como una implementación de la API descrita anteriormente ni como una garantía de que la duración, la resolución o la calidad de salida sean idénticas.
Cherrypop es gratuito al principio, pero tiene algunas limitaciones; para acceder a determinados contenidos multimedia puede ser necesario disponer de una suscripción Premium o de «Cherries». Consulta el coste de la operación que se muestra. Crea el personaje y la escena inicial cuando la interacción es tan importante como el vídeo.