Skip to content
PleumRouter

Video Generation (async)

비동기 작업으로 영상을 생성합니다. 작업을 제출하고 완료될 때까지 폴링합니다.

영상 생성은 비동기 작업 모델을 사용합니다. 먼저 POST /v1/video/generations로 작업을 제출하면 즉시 job_id가 반환되고, 이어서 GET /v1/jobs/{job_id}로 작업이 완료될 때까지 상태를 폴링합니다. 모든 요청에는 plm_ API 키가 필요합니다.

작업 제출#

POST/v1/video/generations
파라미터타입필수설명
modelstring선택모델 ID. 기본값 veo-3.
promptstring필수생성할 영상에 대한 설명. 최대 4,000자.
duration_secondsinteger선택영상 길이(초). 1 ~ 60. 기본값 8.
request
curl https://router.pleum.ai/v1/video/generations \
  -H "Authorization: Bearer $PLEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3",
    "prompt": "A drone shot flying over a misty mountain valley at sunrise",
    "duration_seconds": 8
  }'

작업을 제출하면 status가 processing인 작업 객체가 반환됩니다. result_url과 cost는 작업이 완료되기 전까지 null입니다.

제출 직후 반환되는 작업 객체:

202 Accepted
{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "processing",
  "model": "veo-3",
  "result_url": null,
  "cost": null,
  "error": null
}

작업 폴링#

GET/v1/jobs/{job_id}

GET /v1/jobs/{job_id}로 작업 상태를 조회합니다. 제출 응답과 동일한 형태를 반환하며, 작업이 진행 중인 동안 status는 processing으로 유지됩니다.

request
curl https://router.pleum.ai/v1/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer $PLEUM_API_KEY"

성공하면 status가 succeeded로 바뀌고 result_url에 영상 URL이, cost에 원화 비용 ({"krw": <int>})이 채워집니다. 실패하면 status가 failed가 되고 error에 사유가 담깁니다.

200 OK (succeeded)
{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "succeeded",
  "model": "veo-3",
  "result_url": "https://cdn.pleum.ai/video/f47ac10b-58cc-4372-a567-0e02b2c3d479.mp4",
  "cost": {"krw": 4200},
  "error": null
}

상태 라이프사이클#

status는 다음 네 가지 값을 가집니다:

processing — 작업이 큐에 있거나 생성 중입니다.

succeeded — 완료됨. result_url과 cost가 채워집니다.

failed — 실패함. error에 사유가 담깁니다.

canceled — 작업이 취소되었습니다.

비동기 영상 생성은 BYOK(자기 키)를 지원하지 않습니다. BYOK 키로 요청하면 400이 반환됩니다 — 관리형 키를 사용하세요. 존재하지 않거나(UUID 형식이 아니거나) 본인 소유가 아닌 job_id를 조회하면 404가 반환됩니다.