영상 생성

POST /v1/video/generations

영상 작업을 제출하고 즉시 task_id 를 반환합니다. 모델·길이·해상도에 따라 다르지만 보통 1~5분이 걸립니다. 경로와 응답 형태를 new-api 의 영상 채널에 맞췄기 때문에 중계 게이트웨이에서 그대로 영상 채널로 붙일 수 있습니다.

요청 파라미터

파라미터	타입	설명
prompt	string	필수. 영상 설명
model	string	/v1/models 의 모델 id. 생략 시 기본 모델
mode	string	text=텍스트 기반(기본) \| image=이미지 기반
duration	integer	초 단위 길이. 선택한 사양의 min_sec ~ max_sec 로 보정
resolution	string	480p \| 720p \| 1080p \| 4k. spec 지정 시 그쪽이 우선
ratio	string	adaptive \| landscape \| portrait \| 16:9 \| 9:16 \| 4:3 \| 3:4 \| 1:1 \| 21:9. 생략하면 width/height 로 가로·세로를 판단하고, 둘 다 없으면 adaptive. 그 외의 값은 오류. 선택한 모델이 어떤 비율을 허용하는지는 /v1/models 의 aspect_ratios 참조
width / height	integer	픽셀 표기. ratio 가 없을 때만 가로·세로 판별에 사용. 두 값이 같으면 adaptive 로 처리
spec	string	사양 키. 해상도와 초당 단가를 결정
image	string	시작 프레임 주소. mode=image 일 때 사용
image_last	string	끝 프레임 주소. image 와 함께 쓰면 시작·끝 프레임 모드
reference_images	string[]	피사체 일관성을 위한 참조 이미지
reference_videos	string[]	참조 동영상 공개 URL. reference_video_durations 와 인덱스별로 대응
reference_video_durations	number[]	각 참조 동영상의 길이(초). 탐지 가능한 양수여야 함
reference_audios	string[]	참조 오디오 공개 URL. reference_audio_durations 와 인덱스별로 대응
reference_audio_durations	number[]	각 참조 오디오의 길이(초). 탐지 가능한 양수여야 함

mode=image 일 때는 image 또는 reference_images 중 하나가 반드시 필요하며, 둘 다 비면 오류입니다. 참조 동영상과 오디오는 모델 기능에 따라 지원됩니다. 선택한 사양의 reference_media_max_sec>0 이면 관련 미디어마다 탐지 가능한 양수 길이를 제출해야 하며, 참조 동영상을 초당 과금할 때도 reference_video_durations 가 필요합니다. 미지원 또는 한도 초과 입력은 명시적으로 거부됩니다. n 이 2 이상이어도 거부합니다. 영상은 편당 과금하고 편당 호출 제한이 걸리므로 요청을 나눠서 제출하세요.

요청 예시

bash

curl https://open.pikpikgo.com/v1/video/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "카메라가 천천히 다가가고, 소녀가 돌아보며 미소 짓는다",
    "mode": "text",
    "duration": 5,
    "resolution": "720p"
  }'

응답 예시

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": "카메라가 천천히 다가가고, 소녀가 돌아보며 미소 짓는다"
}

status 가 processing 이면 렌더러에 전달된 상태입니다. 반환된 task_id 로 아래 조회 엔드포인트를 폴링하세요. 생성에 실패하면 크레딧은 자동 환원됩니다.

영상 작업 조회

GET /v1/video/generations/{task_id} — 영상 작업은 이 엔드포인트로 폴링합니다. /v1/tasks/{id} 가 아닙니다(그쪽은 이미지 전용). 형태는 제출 응답과 같으며, 완료되면 url 이 결과 영상, format 이 그 컨테이너 형식입니다.

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": "카메라가 천천히 다가가고, 소녀가 돌아보며 미소 짓는다"
}

error 는 성공 시 빈 문자열이 아니라 null 입니다. 실패 판별은 status 나 error !== null 로 하세요. 작업은 그것을 만든 계정만 조회할 수 있으며, 남의 작업과 존재하지 않는 작업은 완전히 동일한 404를 반환합니다.