WaveSpeedAI

API de Genjutsu: envía un vídeo de Object Swap

Usa la API de Genjutsu para una solicitud de Object Swap: prepara un clip de origen, envía el trabajo y recupera el vídeo editado.

By John7 min read
API de Genjutsu: envía un vídeo de Object Swap

Una función de edición de vídeo puede devolver un trabajo exitoso y aun así dejar a tu equipo con un recurso inutilizable: se procesó la parte equivocada del clip, el reemplazo cambia entre fotogramas o nadie guardó el resultado. Para una integración con la API de Genjutsu, haría que cada edición fuera trazable desde la entrada hasta el archivo aprobado. El inicio rápido de la API de Higgsfield describe el flujo de enviar, consultar y recuperar; esta guía lo aplica a una única solicitud de Object Swap.

Higgsfield proporciona el modelo y el endpoint. Si tu producto usa WaveSpeedAI, consulta su directorio de modelos para esta operación concreta y su propio esquema de solicitud. No des por hecho que otro modelo de intercambio en vídeo acepte una solicitud de Higgsfield.

¿Qué necesita una solicitud de Object Swap de Genjutsu?

Una solicitud necesita la URL de un vídeo de origen y de una a ocho URL de imágenes de referencia. El prompt es opcional. resolution es 720p por defecto; también se indican 480p y 1080p. La referencia de la API de Object Swap identifica el modelo como higgsfield/genjutsu/object-swap/v1.0. Requiere un vídeo de al menos cuatro segundos y de al menos 409 600 píxeles por fotograma.

Revisa el clip antes de enviarlo. Los vídeos de más de 30 segundos se recortan a 30 segundos, y el resultado sigue esa duración preparada. Si la edición prevista ocurre en el segundo 34, una solicitud exitosa no podrá entregarla. Selecciona primero el segmento y registra después qué segmento enviaste.

Una solicitud desde el servidor puede tener esta forma. Las URL y las variables de entorno son ilustrativas:

curl -X POST \
  "https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0" \
  -H "Authorization: Key ${HF_KEY}" \
  -H "Idempotency-Key: ${EDIT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/approved-source.mp4",
    "image_urls": ["https://example.com/approved-object.png"],
    "prompt": "Replace the featured cup with the reference cup.",
    "resolution": "720p"
  }'

Mantén la credencial en tu servidor. Asigna a cada edición lógica su propia clave de idempotencia estable, de modo que un envío ambiguo pueda reintentarse sin crear deliberadamente un segundo trabajo. Si el origen muestra a una persona identificable, o usa material o ilustraciones protegidos, obtén los derechos y el consentimiento necesarios antes de subirlo. Esto es un recordatorio para producción, no asesoramiento legal.

Envía la edición y sigue su estado

Un POST exitoso acepta el trabajo; no devuelve un vídeo terminado. Guarda el request_id, el status_url y el cancel_url de la respuesta en el registro de edición de tu producto. Usa esas URL devueltas en lugar de construirlas tú mismo.

La documentación del ciclo de vida de las solicitudes de Higgsfield indica queued e in_progress como estados no terminales. Deja de esperar cuando el estado pase a completed, failed, nsfw o canceled. Muestra esos resultados por separado en tu interfaz. «Aún procesando» es una mala respuesta cuando el proveedor ya ha rechazado el trabajo.

Empieza a consultar el estado con intervalos de unos dos segundos y aumenta el intervalo si la espera es más larga. Si una consulta de estado encuentra un error de red transitorio, reintenta la consulta de estado. No envíes otro POST de edición solo porque una consulta haya fallado. Guarda el estado final y cualquier error devuelto junto con el ID de la solicitud, para que el soporte pueda distinguir una generación fallida de una sesión del navegador que terminó antes de tiempo.

Recupera y revisa el vídeo terminado

Cuando el estado sea completed, lee video.url del resultado. Descarga el archivo a un almacenamiento que controle tu producto y comprueba que se reproduce y que coincide con la edición prevista. Un trabajo de API completado es un candidato para entregar, no una decisión de aprobación.

Revisa algo más que una miniatura. Comprueba el reemplazo al principio, en la mitad y al final del clip, en particular donde el objeto pasa detrás de otro sujeto o cruza el encuadre. Compara la duración procesada con el segmento que enviaste. Si el sonido importa para la función, inspecciona también la pista de audio del resultado; la referencia de Object Swap no promete conservar el audio original.

Un buen resultado aislado no significa que el flujo de producción esté listo. La finalización del proveedor indica que existe un archivo. Tu comprobación de aceptación decide si ese archivo puede entrar en el producto.

Haz reproducible el Object Swap en producción

Guarda un manifiesto de edición reproducible

Conserva juntos la versión del recurso de origen, el intervalo de tiempo seleccionado, las versiones de las imágenes de referencia, el prompt, la resolución, el ID del modelo, la clave de idempotencia, el ID de la solicitud y el estado final. Añade la ubicación de almacenamiento del resultado aprobado. Una persona puede recordar los parámetros. Un equipo no.

Este registro ayuda cuando un editor pide «el mismo intercambio, pero con el producto azul». El equipo puede cambiar una entrada de forma deliberada en lugar de reconstruir la solicitud anterior a partir de un archivo llamado final-v3.mp4.

Archiva el original y el resultado aprobado

Conserva el clip original para poder revertir y guarda el resultado aprobado fuera de la ubicación temporal de medios del proveedor. Los términos de la API sobre retención y consentimiento de Higgsfield indican que los medios generados están disponibles durante al menos siete días, pero pueden eliminarse después. Eso no garantiza una URL permanente. Registra si el resultado fue aceptado, rechazado o devuelto para revisión, y por qué.

Preguntas frecuentes

¿Object Swap conserva el audio del clip de origen?

La referencia publicada de Object Swap no lo dice. No prometas que el audio se conserva en tu producto. Prueba con un clip autorizado que contenga una pista de audio reconocible e inspecciona el archivo devuelto antes de afirmar esa función.

¿Se puede cancelar una solicitud de Genjutsu en cola?

Sí, mientras siga siendo elegible en la cola. Envía una solicitud de cancelación al cancel_url devuelto; simplemente detener tu proceso de consulta no cancela el trabajo. Una vez que comienza el procesamiento, la cancelación deja de estar disponible según el ciclo de vida documentado.

¿Qué ocurre si la URL de origen caduca durante la preparación?

La documentación no especifica un único punto de fallo universal para una URL de entrada de Object Swap que caduca. Mantén el origen accesible mientras Higgsfield pueda necesitar descargarlo. Si la preparación falla, registra el estado real de la solicitud y el error. Que se acepte el POST no demuestra que el archivo ya se haya descargado.

¿Un fallo en la preparación de la entrada consume unidades de facturación?

Depende del fallo notificado. La guía de facturación y retención de Higgsfield indica que las solicitudes que terminan en failed o nsfw no se cobran y que los créditos reservados se reembolsan. «Fallo en la preparación de la entrada» no es en sí un estado de facturación, así que revisa la respuesta y el registro de facturación en lugar de aplicar la misma regla a todos los errores de este tipo.

¿Cuánto tiempo permanece disponible la URL del vídeo completado?

Los medios generados son accesibles durante al menos siete días y pueden eliminarse después. Descarga cuanto antes un vídeo aprobado. Para una función de la API de Genjutsu que los usuarios puedan volver a consultar semanas después, sirve la copia guardada desde tu propio almacenamiento.


Publicaciones anteriores:

Compartir