문서로 돌아가기

동영상 생성 API

API 키로 Veo 3.1 텍스트-동영상, 이미지-동영상 작업을 만들고, 이미지와 같은 /api/status 엔드포인트로 결과를 조회하세요.

Nano AI API 기본 URL: https://nanobnana.com

인증

모든 요청에 API 키를 Bearer 토큰으로 보내세요. 작업 생성과 상태 조회에는 같은 키를 사용해야 합니다. 키는 대시보드의 API Keys 페이지에서 만들 수 있습니다.

http
Authorization: Bearer YOUR_API_KEY

모델과 크레딧

model 필드에는 아래 값 중 하나를 넣으세요. 다른 값은 HTTP 400으로 거부되며 크레딧이 차감되지 않습니다.

model 값모델텍스트-동영상 (크레딧)이미지-동영상 (크레딧)
veo3_fastVeo 3.1 Fast (기본값)2535
veo3Veo 3.1 Quality180180

veo3-fast는 veo3_fast의 별칭으로 사용할 수 있습니다. model을 생략하면 veo3_fast가 사용됩니다. image_urls에 URL이 하나 이상 있으면 이미지-동영상 요금이 적용됩니다.

동영상 작업 만들기

요청을 검증하고 크레딧을 차감한 뒤 task_id를 반환합니다. 동영상은 비동기로 생성됩니다. /api/status를 조회하거나 callback_url을 설정해 결과를 받으세요.

요청 본문JSON
prompt:string

생성할 동영상에 대한 텍스트 설명.

model:선택string

veo3_fast(별칭 veo3-fast) 또는 veo3. 다른 값은 HTTP 400을 반환합니다. 기본값 veo3_fast.

image_urls:선택string[]

이미지-동영상에 사용할 공개 이미지 URL. 1장이면 그 이미지를 중심으로 동영상이 만들어지고, 2장이면 첫 프레임과 마지막 프레임이 됩니다. 카멜 표기 imageUrls도 별칭으로 사용할 수 있습니다. 두 필드를 모두 보내면 image_urls가 사용됩니다.

aspect_ratio:선택string

16:9, 9:16 또는 Auto. Auto는 업로드한 이미지에 맞춰 동영상을 자릅니다. 기본값 16:9.

translation:선택boolean

true이면 생성 전에 프롬프트를 영어로 번역합니다. 기본값 true.

watermark:선택string

동영상에 넣을 워터마크 텍스트.

callback_url:선택string

작업이 끝나면 최종 결과를 POST 요청으로 받을 공개 URL.

지원하지 않는 필드

duration, resolution, 단수형 image_url은 이 API에 포함되지 않으며 무시됩니다. 동영상 길이는 모델이 정합니다. 이미지는 image_urls 배열로 보내세요.

bash
curl -X POST "https://nanobnana.com/api/video/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The camera slowly pushes in as the city lights turn on at dusk",
    "model": "veo3_fast",
    "image_urls": ["https://example.com/first-frame.jpg"],
    "aspect_ratio": "16:9"
  }'
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "veo24223f74e4f445ec9c4403b532cc328fbksv"
  }
}

작업 상태 확인

동영상 작업 ID는 veo로 시작하고 bksv로 끝납니다. /api/status가 자동으로 인식하며, 작업이 완료되면 동영상 URL을 반환합니다.

쿼리 파라미터
task_id:string

POST /api/video/generate가 반환한 task_id.

model:선택string

task_id가 veo…bksv 형식이 아닐 때 veo3로 설정하면 동영상 작업으로 조회합니다.

bash
curl "https://nanobnana.com/api/status?task_id=veo24223f74e4f445ec9c4403b532cc328fbksv" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "veo24223f74e4f445ec9c4403b532cc328fbksv",
    "request": {
      "prompt": "The camera slowly pushes in as the city lights turn on at dusk",
      "model": "veo3_fast",
      "image_urls": [
        "https://example.com/first-frame.jpg"
      ],
      "aspect_ratio": "16:9"
    },
    "response": null,
    "status": "IN_PROGRESS",
    "status_code": 3,
    "status_text": "IN_PROGRESS",
    "consumed_credits": 35,
    "created_at": "2026-10-04 17:05:12",
    "model": "veo3"
  },
  "model": "veo3"
}

상태 값

  • IN_PROGRESS · status_code: 3 — 동영상이 아직 생성 중입니다. 계속 조회하세요.
  • COMPLETED · status_code: 1 — 동영상이 준비되었습니다. response에 동영상 URL이 들어 있습니다.
  • FAILED · status_code: 2 — 생성에 실패했습니다. error_message에 이유가 있으며 크레딧은 자동으로 환불됩니다.

과금과 환불

  • 크레딧은 작업을 만들 때, 생성이 시작되기 전에 차감됩니다.
  • 생성 요청이 HTTP 200을 반환하지 않으면 작업이 만들어지지 않으며, 차감된 크레딧은 즉시 환불됩니다. 응답에 환불된 크레딧 수가 표시됩니다.
  • 생성된 작업이 나중에 FAILED로 끝나면 크레딧이 자동으로 환불되고, 상태 응답의 consumed_credits가 0이 됩니다.

조회 예시

동영상 생성에는 보통 몇 분이 걸립니다. status_code가 3인 동안 10초마다 조회하고, 1 또는 2가 되면 멈추세요.

javascript
async function waitForVideo(taskId) {
  while (true) {
    const res = await fetch(`https://nanobnana.com/api/status?task_id=${taskId}`, {
      headers: { Authorization: 'Bearer YOUR_API_KEY' }
    });
    const payload = await res.json();
    if (!res.ok) throw new Error(payload.message);

    const task = payload.data;
    if (task.status_code === 1) return task.response[0];
    if (task.status_code === 2) throw new Error(task.error_message || 'Video generation failed');

    await new Promise((resolve) => setTimeout(resolve, 10000));
  }
}

콜백

callback_url을 설정하면 작업이 완료되거나 실패할 때 아래 JSON을 담은 POST 요청을 보냅니다. URL은 공용 인터넷에서 접근할 수 있어야 합니다.

{
  "code": 200,
  "message": "success",
  "data": {
    "request": {
      "prompt": "The camera slowly pushes in as the city lights turn on at dusk",
      "model": "veo3_fast",
      "image_urls": [
        "https://example.com/first-frame.jpg"
      ],
      "aspect_ratio": "16:9"
    },
    "response": [
      "https://example.com/generated-video.mp4"
    ],
    "status": "COMPLETED",
    "created_at": "2026-10-04 17:05:12"
  }
}

자주 발생하는 오류

{
  "code": 400,
  "message": "prompt is required",
  "data": null
}