Veo 3 및 Sora API 빠른 시작 — 5분 만에 텍스트-비디오와 이미지-비디오 구현

Veo 3와 Sora는 텍스트-투-비디오를 18개월 전 텍스트-투-이미지가 도달했던 것과 같은 품질 기준으로 끌어올립니다. 문제는 제공업체들이 대기 목록, 지역 제한, 그리고 다른 AI 스택과 잘 맞지 않는 맞춤형 결제 절차 뒤에 액세스를 제한한다는 점입니다.

현재 Kunavo에서 이용할 수 있는 텍스트-투-비디오 모델은 Google Veo 3이며, 하나의 OpenAI 호환 엔드포인트를 통해 제공됩니다 — 대기 목록이 없고, OpenAI 호환 인증을 사용하며, 동영상 단위로 과금하고, 결과는 영구 URL로 제공됩니다. Sora(sora-2)는 로드맵에 있습니다. 엔드포인트가 모델에 종속되지 않으므로 나중에 전환할 때는 model 값의 한 단어만 변경하면 됩니다. 이 가이드를 따라 약 5분 안에 첫 Veo 3 호출을 실행할 수 있습니다. 전체 내용은 Sora API 가이드를 참조하세요.

설정

1. kunavo.com/app/signup에서 가입하세요. $10부터 충전하는 종량제 방식으로, 이 가이드의 모든 예제를 여러 번 실행하기에 충분하며 잔액은 만료되지 않습니다.
2. /app/keys에서 키를 생성하세요. 키는 sk-kn-로 시작합니다.
3. 키를 내보내세요: export KUNAVO_API_KEY=sk-kn-....

Veo 3로 텍스트-투-비디오 생성하기

Veo 3는 영화 같은 장면을 만드는 데 현재 시장에서 가장 뛰어난 텍스트-투-비디오 모델입니다. 카메라 언어(돌리, 푸시인, 랙 포커스)를 이해하고, 컷 전환에서도 안정적인 조명을 생성하며, 24fps 동작을 정확히 처리합니다. 생성에는 30초에서 몇 분이 걸리며 HTTP 응답은 동기식이므로 클라이언트 타임아웃을 길게 설정하세요.

import requests, os, time

KEY = os.environ["KUNAVO_API_KEY"]

resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "model": "veo-3",
        "prompt": "A drone shot pulling back from a quiet mountain lake at dawn, mist rising off the water. Cinematic, 24fps, soft golden light.",
        "aspect_ratio": "16:9",
        "resolution": "1080p",
    },
    timeout=600,   # generations take 30s to several minutes
)
resp.raise_for_status()
data = resp.json()
print(data["data"][0]["url"])

duration은 초 단위 값으로, 초당 과금 모델, 즉 Seedance 모델들과 Wan 2.7에서 클립 길이를 지정합니다. Veo 모델은 이 값을 무시하며, 모든 Veo 클립은 8초이고 동영상당 과금됩니다.

응답은 OpenAI 스타일입니다: { data: [{ url: '...' }] }. URL은 영구적이며 files.kunavo.com에서 제공됩니다. 장기 호스팅이 필요하다면 한 번 다운로드하여 자체 스토리지에 저장하세요.

이미지-동영상

이미지로 기준을 잡는 것이 일반적으로 프로덕션 품질의 결과를 얻는 방법입니다. Veo 3는 두 가지 이미지 모드를 지원합니다:

• image_mode: "frame" — 단일 이미지는 첫 프레임이고, 두 이미지는 첫 프레임 + 마지막 프레임입니다. image_url의 기본값입니다.
• image_mode: "reference" — 프레임을 강제하지 않고 캐릭터/의상 일관성을 유지하기 위한 스타일 참조를 최대 3개까지 제공합니다.

# image-to-video: pass an image_url to anchor the first frame.
resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "model": "veo-3",
        "prompt": "She smiles, then walks out of frame to the left",
        "image_url": "https://files.kunavo.com/<your-upload>.jpg",
        "image_mode": "frame",      # one image => first frame
        "aspect_ratio": "9:16",     # vertical, mobile-native
    },
    timeout=600,
)
print(resp.json()["data"][0]["url"])

기준 이미지의 공개 URL이 아직 없다면 바이트를 /v1/files에 게시하세요. 그러면 Kunavo가 files.kunavo.com 아래에 파일을 호스팅합니다:

# If you don't have a public URL, upload bytes; Kunavo hosts the file.
with open("anchor.jpg", "rb") as f:
    up = requests.post(
        "https://api.kunavo.com/v1/files",
        headers={"Authorization": f"Bearer {KEY}"},
        files={"file": f},
    )
image_url = up.json()["url"]   # permanent files.kunavo.com URL

Sora 및 기타 모델

카탈로그의 모든 동영상 모델에서 동일한 엔드포인트 형식을 사용할 수 있습니다 — 해당 모델 슬러그를 전달하세요:

• veo-3 — 영화적 스타일, 1080p, 이미지-투-비디오 지원. 현재 제공 중입니다.
• seedance-2, seedance-2-5 — ByteDance 모델로, 캐릭터 동작에 매우 강합니다.

OpenAI Sora(sora-2)는 로드맵에 있으며 아직 Kunavo에서 호출할 수 없습니다. /v1/video/generations가 모델에 종속되지 않으므로 제공되는 날에는 위 호출에서 model 필드만 변경하면 됩니다. 그때까지는 Veo 3가 동일한 엔드포인트에서 제공되는 실시간 동등 모델입니다.

실시간 목록과 각 모델의 가격은 /models에서 확인하세요.

Node / TypeScript에서 사용하기

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KUNAVO_API_KEY,
  baseURL: "https://api.kunavo.com/v1",
});

// /v1/video/generations isn't in OpenAI's SDK shape, but the same auth
// header works — call it with fetch:
const resp = await fetch(
  "https://api.kunavo.com/v1/video/generations",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.KUNAVO_API_KEY}`,
    },
    body: JSON.stringify({
      model: "veo-3",
      prompt: "A red origami crane unfolding into a paper plane and flying away through a window",
      resolution: "1080p",
    }),
  },
);
const { data } = await resp.json();
console.log(data[0].url);

가격 모델

동영상 모델은 토큰이 아니라 동영상 단위 또는 출력 초 단위로 과금됩니다. Veo 모델은 동영상 단위이고 모든 클립은 길이가 8초이며, Seedance 모델과 Wan 2.7은 초 단위입니다. Kunavo는 각 모델의 요금을 /pricing에 공개합니다. 8초 Veo 3 1080p 클립은 $0.42입니다. 실패한 생성(4xx / 5xx)에는 절대 요금이 부과되지 않습니다.

프로덕션 체크리스트

• HTTP 타임아웃을 10분으로 설정하세요. 게이트웨이는 최대 540초 동안 upstream을 폴링하며, 그 이후에도 모델이 작업 중이면 504를 반환합니다. 매우 긴 작업은 재시도하세요 — 생성은 프롬프트별로 멱등적입니다.
• 결과 URL을 저장하세요. files.kunavo.com URL은 영구적이지만, 제품에서는 자신이 관리하는 스토리지에 자체 사본을 보관해야 합니다.
• 429 오류에는 백오프를 적용하세요. 동영상 모델은 GPU 리소스에 의해 성능이 제한되므로 짧은 경합은 정상입니다. retry-after 헤더가 있으면 이를 따릅니다.
• 가능하다면 프롬프트 해시를 기준으로 캐시하세요. 동일한 프롬프트를 두 번 보내면 클립이 두 개 생성되고 두 번 과금됩니다. 게이트웨이는 이전 결과를 재사용하지 않으며, 모델에 시드도 보내지 않습니다.

문의: contact@kunavo.com. 게이트웨이를 운영하는 팀이 모든 이메일을 읽고 24시간 이내에 답변합니다.