Sora API 가이드 — 지금 바로 쓰는 AI 영상 생성 (Veo 3)

Sora는 OpenAI의 text-to-video 모델이고, “Sora API”는 소비자용 앱이 아니라 프로그래밍 방식으로 영상을 생성하는 방법입니다. 현재 Kunavo에서 text-to-video는 하나의 OpenAI 스타일 비디오 엔드포인트를 통해 Google Veo 3로 실행됩니다 — 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는 아직 카탈로그에 활성화되지 않았으며, 현재 사용 가능한 text-to-video 모델은 네이티브 오디오와 함께 영화적인 클립을 만드는 Google Veo 3입니다. 아래 예제는 veo-3를 사용하며 — Sora가 추가되면 바꿀 것은 model 필드뿐입니다.

Text-to-video 빠른 시작

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": "빨간 종이학이 펼쳐지는 영화적인 돌리인, 부드러운 조명",
        "duration": 5,
        "aspect_ratio": "16:9",
    },
    timeout=600,  # 생성에 몇 분이 걸릴 수 있습니다
)
print(resp.json()["data"][0]["url"])

Image-to-video

정지 이미지에 움직임을 주려면 프롬프트와 함께 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": "...", "duration": 5, "aspect_ratio": "16:9"},
    timeout=60,
).json()
# 이후 완료될 때까지 GET /v1/videos/{task["id"]} 폴링

비디오 문서는 전체 폴링 루프, 멱등성 키, 웹훅 전달을 다룹니다.

가격

Veo 3는 영상당 과금되며(여기서는 720p 8초 클립 기준), Google 정가보다 약 40~60% 저렴합니다. 해상도가 높을수록 비용이 늘어납니다 — 전체 등급 표는 가격 페이지를 참고하세요.

영상 프롬프트 팁

• 피사체뿐 아니라 샷을 묘사하세요. 카메라 움직임(돌리, 팬, 푸시인), 렌즈 느낌, 조명, 페이싱이 형용사보다 더 중요합니다.
• 화면비를 명시하세요 — 가로는 16:9, 세로/소셜용은 9:16입니다.
• 클립은 짧게 유지하세요. 5~8초가 가장 좋으며, 더 긴 시퀀스는 여러 생성을 이어 붙이세요.
• 레퍼런스 프레임을 사용하세요(image-to-video). 특정 캐릭터나 제품을 일관되게 유지해야 할 때 유용합니다.

자주 묻는 질문

지금 Kunavo에서 Sora API를 쓸 수 있나요?

아직은 아닙니다 — Sora는 카탈로그에 활성화되지 않았습니다. 현재 text-to-video는 동일한 OpenAI 스타일 엔드포인트를 통해 Veo 3로 실행되며, 나중에 Sora로 전환하는 것은 model 한 단어를 바꾸는 일입니다. Sora 지원은 로드맵에 있습니다.

영상 생성 비용은 얼마인가요?

Veo 3는 영상당 과금되며 Google 정가보다 약 40~60% 저렴합니다: Lite는 $0.16부터, Fast는 $0.32부터, Quality는 8초 720p 클립당 $1.92부터입니다.

Kunavo는 image-to-video를 지원하나요?

네 — /v1/video/generations에 image_url을 전달하거나, 제어된 전환을 위해 첫 프레임/마지막 프레임 쌍을 전달하세요.

생성에는 얼마나 걸리나요?

몇 분입니다. 프로덕션에서는 비동기 /v1/videos 작업 API를 사용해 폴링하세요. 비디오 문서를 참고하세요.