Generate videos

POST /v1/video/generations

Submits a video job and returns a task_id immediately. Rendering usually takes one to five minutes depending on model, duration and resolution. The path and response shape match the new-api video channel, so relay gateways can use this platform as a video provider as is.

Parameters

Parameter	Type	Description
prompt	string	Required. What to render
model	string	Model id from /v1/models. Defaults to the platform default
mode	string	text (default) or image
duration	integer	Seconds. Clamped to the chosen spec min_sec – max_sec
resolution	string	480p \| 720p \| 1080p \| 4k. Overridden by spec
ratio	string	adaptive \| landscape \| portrait \| 16:9 \| 9:16 \| 4:3 \| 3:4 \| 1:1 \| 21:9. Omit it and width/height decide the orientation, or adaptive if neither is given. Anything else is an error. Which of these the chosen model accepts is in aspect_ratios from /v1/models
width / height	integer	Pixel form, used only when ratio is absent to pick landscape or portrait. Equal values fall back to adaptive
spec	string	Spec key. Determines resolution and per-second price
image	string	First frame URL, used when mode is image
image_last	string	Last frame URL. Together with image this is first/last frame mode
reference_images	string[]	Reference images for subject consistency
reference_videos	string[]	Public reference-video URLs; positionally aligned with reference_video_durations
reference_video_durations	number[]	Duration in seconds for each reference video; every value must be a detectable positive number
reference_audios	string[]	Public reference-audio URLs; positionally aligned with reference_audio_durations
reference_audio_durations	number[]	Duration in seconds for each reference audio file; every value must be a detectable positive number

With mode=image you must supply image or reference_images; both empty is an error. Reference video and audio are capability-dependent. When the selected spec has reference_media_max_sec>0, every related media item requires a detectable positive duration; per-second reference-video pricing also requires reference_video_durations. Unsupported or over-limit input is rejected explicitly. n greater than 1 is rejected too — videos are billed and rate limited per clip, so submit separate requests.

Request

bash

curl https://open.pikpikgo.com/v1/video/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "slow dolly in, a girl turns back and smiles",
    "mode": "text",
    "duration": 5,
    "resolution": "720p"
  }'

Response

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": "slow dolly in, a girl turns back and smiles"
}

status processing means the job reached the renderer. Poll the endpoint below with the returned task_id. Credits are refunded automatically if rendering fails.

Retrieve a video task

GET /v1/video/generations/{task_id} — video jobs are polled here, not at /v1/tasks/{id} (that one serves images only). The shape matches the submit response; once finished, url is the rendered clip and format is its container.

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": "slow dolly in, a girl turns back and smiles"
}

error is null on success, not an empty string — test failure with status or error !== null. A task can only be read by the account that created it; someone else’s task and a task that never existed both return the same 404.