Gerar vídeos

POST /v1/video/generations

Submete um trabalho de vídeo e devolve de imediato um task_id. A renderização costuma demorar entre um e cinco minutos, conforme o modelo, a duração e a resolução. O caminho e a estrutura da resposta correspondem ao canal de vídeo do new-api, pelo que os gateways de reencaminhamento podem ligar a plataforma como fornecedor de vídeo tal como está.

Parâmetros

Parâmetro	Tipo	Descrição
prompt	string	Obrigatório. O que gerar
model	string	id de modelo de /v1/models. Sem ele, o modelo predefinido
mode	string	text (predefinição) ou image
duration	integer	Segundos. Ajustado ao intervalo min_sec – max_sec do nível escolhido
resolution	string	480p \| 720p \| 1080p \| 4k. spec tem prioridade
ratio	string	adaptive \| landscape \| portrait \| 16:9 \| 9:16 \| 4:3 \| 3:4 \| 1:1 \| 21:9. Se for omitido, width/height decidem a orientação; na falta de ambos, adaptive. Qualquer outro valor dá erro. As proporções aceites pelo modelo escolhido estão em aspect_ratios de /v1/models
width / height	integer	Forma em píxeis, usada apenas quando falta ratio para escolher entre horizontal e vertical. Valores iguais recaem em adaptive
spec	string	Chave de nível. Define a resolução e o preço por segundo
image	string	URL do primeiro fotograma, usado com mode=image
image_last	string	URL do último fotograma. Com image ativa o modo primeiro/último fotograma
reference_images	string[]	Imagens de referência para manter a coerência do sujeito
reference_videos	string[]	URLs públicas de vídeos de referência; correspondem por índice a reference_video_durations
reference_video_durations	number[]	Duração em segundos de cada vídeo de referência; cada valor tem de ser um número positivo detetável
reference_audios	string[]	URLs públicas de áudios de referência; correspondem por índice a reference_audio_durations
reference_audio_durations	number[]	Duração em segundos de cada áudio de referência; cada valor tem de ser um número positivo detetável

Com mode=image é preciso indicar image ou reference_images; ambos vazios dá erro. Vídeo e áudio de referência dependem das capacidades do modelo. Se reference_media_max_sec>0, cada elemento multimédia relacionado exige uma duração positiva detetável; a faturação por segundo do vídeo de referência também exige reference_video_durations. Entradas não suportadas ou acima do limite são recusadas explicitamente. n maior que 1 também é recusado: o vídeo é faturado e limitado por clipe, por isso envia pedidos separados.

Pedido

bash

curl https://open.pikpikgo.com/v1/video/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "travelling lento para a frente, uma rapariga volta-se e sorri",
    "mode": "text",
    "duration": 5,
    "resolution": "720p"
  }'

Resposta

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 para a frente, uma rapariga volta-se e sorri"
}

status processing significa que o trabalho já chegou ao motor de renderização. Sonda o endpoint abaixo com o task_id devolvido. Se a renderização falhar, os créditos são devolvidos automaticamente.

Consultar tarefa de vídeo

GET /v1/video/generations/{task_id}: as tarefas de vídeo sondam-se aqui, não em /v1/tasks/{id} (esse só serve imagem). A estrutura é a mesma da resposta de submissão; quando termina, url é o clipe renderizado e format o respetivo contentor.

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 para a frente, uma rapariga volta-se e sorri"
}

error é null quando corre bem, não uma cadeia vazia: testa a falha com status ou com error !== null. Uma tarefa só pode ser lida pela conta que a criou; a tarefa de outra pessoa e uma que nunca existiu devolvem exatamente o mesmo 404.