Sora API 사용법 — 지금 바로 실행되는 AI 비디오 생성(Veo 3.1 / OpenAI 호환)

Sora는 OpenAI의 텍스트-동영상 생성 모델이며 ‘Sora API’는 소비자용 앱이 아니라 프로그램으로 동영상을 생성하는 방법입니다. Kunavo에서는 현재 텍스트-동영상 생성이 Google Veo 3를 통해 하나의 OpenAI 스타일 동영상 엔드포인트에서 작동합니다. Sora 지원은 로드맵에 있으며 엔드포인트는 모델에 종속되지 않으므로 나중에 Sora로 전환할 때는 한 단어만 바꾸면 됩니다. 이 가이드에서는 모든 예제가 지금 바로 작동하도록 Veo 3를 사용해 워크플로를 보여 줍니다.

Sora API란?

Sora(Sora 2 및 Sora 2 Pro)는 텍스트 프롬프트 또는 정지 이미지 한 장을 짧은 동영상 클립으로 변환하며, Sora 2에서는 동기화된 오디오도 함께 제공합니다. API 형태로 사용하면 생성을 파이프라인에 통합할 수 있습니다. 예를 들어 마케팅 영상, 제품 애니메이션, B-roll, 스토리보드 미리보기 등에 사용할 수 있습니다. 형태는 최근 동영상 모델 전반에서 공통적이며, 프롬프트와 매개변수를 보내고 호스팅된 동영상 URL을 받습니다.

Kunavo에서 현재 사용할 수 있는 동영상: Veo 3

Kunavo는 하나의 OpenAI 스타일 엔드포인트 /v1/video/generations를 통해 동영상 생성을 제공합니다. Sora는 아직 카탈로그에서 활성화되지 않았으며, 현재 사용할 수 있는 텍스트-동영상 모델은 Google Veo 3입니다. 이 모델은 네이티브 오디오가 포함된 영화 같은 클립을 생성합니다. 아래 예제에서는 veo-3을 사용합니다. Sora가 추가되면 변경할 것은 model 필드뿐입니다.

텍스트-동영상 빠른 시작

Kunavo 키로 POST를 한 번만 보내면 됩니다. 생성에는 몇 분이 걸릴 수 있으므로 동기 호출은 클립이 준비될 때까지 연결을 유지합니다.

import requests

resp = requests.post(
    "https://api.kunavo.com/v1/video/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "veo-3",
        "prompt": "a cinematic dolly-in on a red origami crane unfolding, soft light",
        "aspect_ratio": "16:9",
    },
    timeout=600,  # 生成には数分かかることがあります
)
print(resp.json()["data"][0]["url"])

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

이미지-동영상

정지 이미지를 애니메이션으로 만들려면 프롬프트와 함께 image_url(HTTPS URL 또는 /v1/files에 업로드한 파일)을 전달합니다. 움직임을 제어하려면 image_urls 및 image_mode: "frame"로 시작 프레임과 마지막 프레임을 전달할 수 있습니다. 자세한 예제는 동영상 문서에서 확인하세요.

비동기 작업 수명 주기

프로덕션에서는 10분 동안 연결을 유지하지 마세요. /v1/videos에 작업을 제출하면 즉시 작업 ID가 반환되므로 완료될 때까지 GET /v1/videos/{id}을 폴링합니다. 결과 URL은 영구적입니다.

# 本番: タスクを投入してからポーリング——長時間の接続を保持しません。
task = requests.post(
    "https://api.kunavo.com/v1/videos",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": "my-task-uuid",   # 約 24 時間はリトライしても安全
    },
    json={"model": "veo-3", "prompt": "...", "aspect_ratio": "16:9"},
    timeout=60,
).json()
# その後 GET /v1/videos/{task["id"]} を完了までポーリングします

동영상 문서에서는 전체 폴링 루프, 멱등성 키, 웹훅 전달을 설명합니다.

요금

Veo 3는 동영상 단위로 과금되며(여기서는 720p 8초 클립 기준) Google 정가보다 약 50〜70% 저렴합니다. 해상도가 높아지면 비용도 증가합니다. 전체 티어 표는 요금 페이지를 참조하세요.

동영상 프롬프트 팁

• 피사체뿐 아니라 샷을 묘사하세요. 카메라 움직임(돌리, 팬, 푸시인), 렌즈의 질감, 조명, 템포가 형용사보다 더 효과적입니다.
• 가로세로 비율을 명시하세요 — 가로 방향이면 16:9, 세로 방향/SNS면 9:16입니다.
• 모든 Veo 클립은 8초입니다. 각 장면을 이 길이에 맞춰 구성하고, 더 긴 시퀀스는 여러 생성 결과를 이어 붙이세요.
• 참조 프레임을 사용하세요(이미지-동영상). 특정 캐릭터나 제품의 일관성을 유지할 때 유용합니다.

자주 묻는 질문