본문으로 건너뛰기
PleumRouter
시작하기

Video Generation

비동기 작업으로 영상을 생성합니다. LTX 2.3 및 BytePlus ModelArk의 모델별 입력 제약을 요청 전에 검증합니다.

POST /v1/video/generations는 즉시 job_id를 반환합니다. 이후 GET /v1/jobs/{job_id}로 완료될 때까지 폴링하세요. 모든 요청에는 plm_ API 키가 필요합니다.

Kling 영상 API 가격·할인 조건·사용법

POST/v1/video/generations

작업 제출#

파라미터타입필수설명
modelstring선택영상 모델 ID. 기본값 veo-3입니다.
promptstring필수영상 설명. 최대 4,000자.
duration_secondsinteger선택요청 길이. 2~20초, 기본값 8. Kling V3는 3~15초 정수, V2.5/V2.6은 5 또는 10초를 명시하며, LTX·ModelArk 모델은 더 좁은 모델별 범위를 적용합니다.
resolution480p | 720p | 1080p | 1440p | 4k선택출력 해상도. 기본값 720p.
generate_audioboolean선택생성 오디오 포함 여부. 기본값 false로, 예기치 않은 audio variant 비용을 피합니다.
imagestring | null선택기존 첫 이미지 URL 별칭입니다. images와 합쳐져 순서를 보존합니다.
imagesstring[]선택입력 이미지 URL. image 별칭과 합친 뒤 최대 9개이며 HTTP(S)만 허용합니다.
videosstring[]선택입력 비디오 reference URL. 최대 3개, HTTP(S)만 허용합니다.
audiosstring[]선택입력 오디오 reference URL. 최대 3개, HTTP(S)만 허용합니다.
charge_amount_krwinteger | null선택고정 KRW 정산 금액. 일반 API 키는 사용할 수 없고 1st-party 위임 키만 허용됩니다.
request
curl https://apirouter.pleum.ai/v1/video/generations \
  -H "Authorization: Bearer $PLEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seedance-shot-001" \
  -d '{
    "model": "dreamina-seedance-2-0-260128",
    "prompt": "A drone shot flying over a misty mountain valley at sunrise",
    "duration_seconds": 8,
    "resolution": "720p",
    "generate_audio": false,
    "images": ["https://example.com/first-frame.png"],
    "videos": ["https://example.com/motion-reference.mp4"]
  }'
submit + poll (Python)
import time, requests

BASE = "https://apirouter.pleum.ai/v1"
HEADERS = {"Authorization": "Bearer plm_...", "Content-Type": "application/json"}

# 1. Submit the job — returns job_id immediately.
resp = requests.post(f"{BASE}/video/generations", headers=HEADERS, json={
    "model": "dreamina-seedance-2-0-260128",
    "prompt": "A drone shot flying over a misty mountain valley at sunrise",
    "duration_seconds": 8,
    "resolution": "720p",
})
job_id = resp.json()["job_id"]

# 2. Poll until the job finishes.
while True:
    job = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS).json()
    if job["status"] in ("succeeded", "failed", "canceled"):
        break
    time.sleep(5)

print(job["result_url"] if job["status"] == "succeeded" else job["error"])
submit + poll (TypeScript)
const BASE = "https://apirouter.pleum.ai/v1";
const HEADERS = { Authorization: "Bearer plm_...", "Content-Type": "application/json" };

// 1. Submit the job — returns job_id immediately.
const submit = await fetch(`${BASE}/video/generations`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    model: "dreamina-seedance-2-0-260128",
    prompt: "A drone shot flying over a misty mountain valley at sunrise",
    duration_seconds: 8,
    resolution: "720p",
  }),
});
const { job_id } = await submit.json();

// 2. Poll until the job finishes.
let job: any;
do {
  await new Promise((r) => setTimeout(r, 5000));
  job = await (await fetch(`${BASE}/jobs/${job_id}`, { headers: HEADERS })).json();
} while (job.status !== "succeeded" && job.status !== "failed");

console.log(job.status === "succeeded" ? job.result_url : job.error);
202 Accepted
{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "processing",
  "model": "dreamina-seedance-2-0-260128",
  "result_url": null,
  "cost": null,
  "error": null,
  "assets": []
}

Provider별 영상 입력 제한#

선택한 LTX 또는 ModelArk 모델의 duration·resolution·reference 조합은 hold 생성 전에 검증됩니다. 지원하지 않는 조합은 비용 없이 400을 반환합니다.

파라미터타입필수설명
Klingduration선택V3는 3~15초 정수, V2.5/V2.6은 5초 또는 10초를 지원합니다. 원하는 길이로 duration_seconds를 명시하세요. Kling은 resolution 선택을 지원하지 않으며 이 파라미터를 보내면 400입니다. 모델: kling-v3, kling-v3-turbo, kling-v3-omni, kling-v2-5-turbo, kling-v2-6.
LTX 2.3 Fast / Produration + resolution선택텍스트→영상 전용입니다. Fast는 1080p에서 6·8·10·12·14·16·18·20초, 1440p/4k에서는 6·8·10초만 지원합니다. Pro는 모든 해상도에서 6·8·10초만 지원합니다. 480p/720p 요청은 LTX의 1080p 출력으로 정규화됩니다.
Seedance 2.0duration + references선택4~15초. 이미지≤9·비디오≤3·오디오≤3. 오디오 reference에는 이미지 또는 비디오 reference가 하나 이상 필요합니다. 이미지 1/2장은 first/last frame이고, 비디오·오디오 또는 3장 이상 이미지와 함께 쓰면 모두 reference_image가 됩니다.
Seedance 2.0 Fast / Miniresolution선택480p 또는 720p만 지원합니다. Mini는 video/audio reference를 지원하지 않습니다.
Seedance 1.5 Produration + references선택4~12초, 4k 미지원. 이미지 reference는 최대 2개이며 video/audio reference는 지원하지 않습니다.
Seedance 1.0 Produration + references선택2~12초, 4k 미지원. 이미지 reference는 최대 2개( Fast는 1개), video/audio reference는 지원하지 않습니다. 1.0은 generate_audio도 지원하지 않습니다.
Gemini Omniresolution선택텍스트→영상 전용. 해상도 720p·1080p·4k(기본 720p). 길이는 모델이 3~10초로 정하므로 duration_seconds를 보내면 400을 반환하고, image/videos/audios reference도 지원하지 않습니다. 정산은 완료 응답이 보고한 출력 토큰 기준입니다. 결과는 아래 “결과 내려받기”의 /content 엔드포인트로 받습니다.

작업 폴링#

GET/v1/jobs/{job_id}

POST 응답의 status는 처음에는 processing입니다. GET /v1/jobs/{job_id}는 같은 작업 객체를 반환하며 완료된 작업의 assets에는 video 결과가 있을 수 있습니다.

status는 processing, succeeded, failed, canceled 중 하나입니다. 성공 시 result_url/cost가 채워지고, 실패·취소 시 error가 반환됩니다. 만료된 upstream task는 failed로 정규화됩니다. Google 모델(Veo·Gemini Omni)의 결과 수신 방법은 아래 “결과 내려받기”를 참고하세요.

succeeded
{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "succeeded",
  "model": "dreamina-seedance-2-0-260128",
  "result_url": "https://cdn.pleum.ai/video/f47ac10b-58cc-4372-a567-0e02b2c3d479.mp4",
  "cost": {"krw": 4200},
  "error": null,
  "assets": [{"type": "video", "url": "https://cdn.pleum.ai/video/f47ac10b-58cc-4372-a567-0e02b2c3d479.mp4"}]
}

결과 내려받기#

GET/v1/jobs/{job_id}/content

대부분의 모델은 result_url이 바로 내려받을 수 있는 URL입니다. Google 모델(Gemini Omni 등)은 result_url이 /v1/jobs/{job_id}/content를 가리키며, 작업을 제출한 API 키를 Authorization 헤더로 보내야 받을 수 있습니다(<video src>처럼 헤더를 붙일 수 없는 곳에는 쓸 수 없습니다). 다른 키는 404, 아직 생성 중이면 409입니다. 단일 Range 요청(206)을 지원하며, Google이 파일을 약 48시간만 보관하므로 그 뒤에는 410을 반환합니다. 다운로드는 과금되지 않으니 완료 후 바로 자체 스토리지로 옮겨 두세요.

download
# When result_url points at /v1/jobs/{job_id}/content, download it with the API key that submitted the job.
curl -L https://apirouter.pleum.ai/v1/jobs/$JOB_ID/content \
  -H "Authorization: Bearer $PLEUM_API_KEY" \
  -o result.mp4

# A single Range request is supported (206 Partial Content).
curl https://apirouter.pleum.ai/v1/jobs/$JOB_ID/content \
  -H "Authorization: Bearer $PLEUM_API_KEY" \
  -H "Range: bytes=0-1048575" -o part.mp4

정산 및 BYOK#

LTX 영상은 선택한 해상도의 초당 요금을 요청 길이로 산정해 hold·정산합니다. ModelArk 영상은 완료 task가 보고한 completion token/출력 사용량으로 최종 정산합니다. Idempotency-Key는 선택 사항(최대 128자)이며 동일 본문을 24시간 재생합니다.

영상과 3D 같은 비동기 생성은 BYOK를 지원하지 않습니다. BYOK 키 요청은 400을 반환합니다. 존재하지 않거나 내 소유가 아닌 job_id도 404입니다.
이전음악 생성다음3D 생성