Generar vídeos

POST /v1/video/generations

Envía un trabajo de vídeo y devuelve un task_id de inmediato. El renderizado suele tardar entre uno y cinco minutos según modelo, duración y resolución. La ruta y la estructura de la respuesta coinciden con el canal de vídeo de new-api, así que las pasarelas de reenvío pueden usar la plataforma como proveedor de vídeo sin más.

Parámetros

Parámetro	Tipo	Descripción
prompt	string	Obligatorio. Qué generar
model	string	id de modelo de /v1/models. Sin él se usa el modelo por defecto
mode	string	text (por defecto) o image
duration	integer	Segundos. Se ajusta al rango min_sec – max_sec del nivel elegido
resolution	string	480p \| 720p \| 1080p \| 4k. spec tiene prioridad
ratio	string	adaptive \| landscape \| portrait \| 16:9 \| 9:16 \| 4:3 \| 3:4 \| 1:1 \| 21:9. Si se omite, width/height deciden la orientación; si faltan ambos, adaptive. Cualquier otro valor da error. Las proporciones que admite el modelo elegido están en aspect_ratios de /v1/models
width / height	integer	Forma en píxeles, solo se usa cuando falta ratio para elegir entre horizontal y vertical. Con valores iguales se vuelve a adaptive
spec	string	Clave de nivel. Determina resolución y precio por segundo
image	string	URL del primer fotograma, usada con mode=image
image_last	string	URL del último fotograma. Junto a image activa el modo primer/último fotograma
reference_images	string[]	Imágenes de referencia para mantener la coherencia del sujeto
reference_videos	string[]	URLs públicas de vídeo de referencia; corresponden por índice con reference_video_durations
reference_video_durations	number[]	Duración en segundos de cada vídeo de referencia; cada valor debe ser un número positivo detectable
reference_audios	string[]	URLs públicas de audio de referencia; corresponden por índice con reference_audio_durations
reference_audio_durations	number[]	Duración en segundos de cada audio de referencia; cada valor debe ser un número positivo detectable

Con mode=image hay que dar image o reference_images; ambos vacíos es un error. El vídeo y el audio de referencia dependen de las capacidades del modelo. Si reference_media_max_sec>0, cada medio relacionado requiere una duración positiva detectable; la tarificación por segundo del vídeo de referencia también exige reference_video_durations. Las entradas no admitidas o que superen el límite se rechazan explícitamente. n mayor que 1 también se rechaza: el vídeo se cobra y se limita por clip, así que envía peticiones separadas.

Petición

bash

curl https://open.pikpikgo.com/v1/video/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "travelling lento hacia delante, una chica se gira y sonríe",
    "mode": "text",
    "duration": 5,
    "resolution": "720p"
  }'

Respuesta

json

{
  "task_id": "2608101915300490318827",
  "id": "2608101915300490318827",
  "object": "video",
  "model": "video-pro-1",
  "created_at": 1786000530,
  "status": "processing",
  "url": "",
  "format": "",
  "metadata": {
    "duration": 5,
    "resolution": "720p",
    "ratio": "adaptive"
  },
  "error": null,
  "credits": 60,
  "prompt": "travelling lento hacia delante, una chica se gira y sonríe"
}

status processing significa que el trabajo ya llegó al renderizador. Sondea el endpoint de abajo con el task_id devuelto. Si el renderizado falla, los créditos se devuelven automáticamente.

Consultar tarea de vídeo

GET /v1/video/generations/{task_id}: las tareas de vídeo se sondean aquí, no en /v1/tasks/{id} (ese solo sirve para imagen). La estructura coincide con la respuesta del envío; al terminar, url es el clip renderizado y format su contenedor.

bash

curl https://open.pikpikgo.com/v1/video/generations/2608101915300490318827 \
  -H "Authorization: Bearer $PIKPIK_API_KEY"

json

{
  "task_id": "2608101915300490318827",
  "id": "2608101915300490318827",
  "object": "video",
  "model": "video-pro-1",
  "created_at": 1786000530,
  "status": "succeeded",
  "url": "https://cdn.pikpikgo.com/video/2608101915300490318827.mp4",
  "format": "mp4",
  "metadata": {
    "duration": 5,
    "resolution": "720p",
    "ratio": "adaptive"
  },
  "error": null,
  "credits": 60,
  "prompt": "travelling lento hacia delante, una chica se gira y sonríe"
}

error es null cuando hay éxito, no una cadena vacía: comprueba el fallo con status o con error !== null. Una tarea solo la puede leer la cuenta que la creó; la tarea de otra persona y una que nunca existió devuelven exactamente el mismo 404.