> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Veo 3 API 빠른 시작: CometAPI로 비디오 생성하기

> CometAPI로 Veo 비디오 작업을 생성하고, 작업 상태를 폴링하며, 완료된 비디오 출력을 curl, Python 또는 Node.js로 저장합니다.

## 만들게 될 것

multipart form data를 사용해 Veo 비디오 작업 하나를 생성하고, 반환된 작업 ID를 저장한 다음, retrieve 엔드포인트를 폴링하여 최종 asset URL 또는 파일을 자체 시스템에 저장합니다.

## 사전 준비 사항

* `COMETAPI_KEY`에 저장된 CometAPI API 키
* `requests`가 설치된 Python 3.10+ 또는 Node.js 18+
* 폴링을 위한 서버 측 작업 실행기

## API 키, base URL, 인증

다음으로 Veo 작업을 생성합니다:

```text theme={null}
POST https://api.cometapi.com/v1/videos
```

다음으로 Veo 작업 상태를 폴링합니다:

```text theme={null}
GET https://api.cometapi.com/v1/videos/<task_id>
```

Bearer 토큰으로 인증합니다:

```text theme={null}
Authorization: Bearer $COMETAPI_KEY
```

## 코드 예제

아래 탭에서 복사 가능한 cURL, Python, Node.js 예제를 사용하세요.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.cometapi.com/v1/videos \
    -H "Authorization: Bearer $COMETAPI_KEY" \
    -F model=veo3.1-fast \
    -F "prompt=A paper kite floats above a field." \
    -F seconds=4 \
    -F size=1280x720

  curl "https://api.cometapi.com/v1/videos/<task_id>" \
    -H "Authorization: Bearer $COMETAPI_KEY"
  ```

  ```python Python theme={null}
  import os
  import time

  import requests

  api_key = os.environ["COMETAPI_KEY"]
  headers = {"Authorization": f"Bearer {api_key}"}

  create_response = requests.post(
      "https://api.cometapi.com/v1/videos",
      headers=headers,
      files={
          "model": (None, "veo3.1-fast"),
          "prompt": (None, "A paper kite floats above a field."),
          "seconds": (None, "4"),
          "size": (None, "1280x720"),
      },
      timeout=60,
  )
  create_response.raise_for_status()
  task_id = create_response.json()["id"]

  for _ in range(60):
      retrieve_response = requests.get(
          f"https://api.cometapi.com/v1/videos/{task_id}",
          headers=headers,
          timeout=30,
      )
      retrieve_response.raise_for_status()
      task = retrieve_response.json()
      if task["status"] in {"completed", "failed", "error"}:
          print(task)
          break
      time.sleep(5)
  else:
      raise TimeoutError("Veo task did not finish in time")
  ```

  ```javascript Node.js theme={null}
  const form = new FormData();
  form.append("model", "veo3.1-fast");
  form.append("prompt", "A paper kite floats above a field.");
  form.append("seconds", "4");
  form.append("size", "1280x720");

  const createResponse = await fetch("https://api.cometapi.com/v1/videos", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
    body: form,
  });

  if (!createResponse.ok) {
    throw new Error(await createResponse.text());
  }

  const { id } = await createResponse.json();

  for (let attempt = 0; attempt < 60; attempt += 1) {
    const retrieveResponse = await fetch(`https://api.cometapi.com/v1/videos/${id}`, {
      headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
    });

    if (!retrieveResponse.ok) {
      throw new Error(await retrieveResponse.text());
    }

    const task = await retrieveResponse.json();
    if (["completed", "failed", "error"].includes(task.status)) {
      console.log(task);
      break;
    }
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
  ```
</CodeGroup>

## 흐름 설명

Veo 비디오 생성은 비동기식입니다. create 엔드포인트는 multipart form data를 받아 즉시 작업 ID를 반환합니다. 작업이 종료 상태에 도달할 때까지 retrieve 엔드포인트를 폴링한 뒤, 완료 응답에서 최종 비디오 URL 또는 파일 세부 정보를 영구 저장하세요.

초기 테스트에서는 짧은 길이와 가장 작은 유효 크기를 사용하세요. 애플리케이션에서 보관이 필요하다면 완료된 asset을 자체 스토리지로 옮기세요.

## 공통 파라미터

| Parameter         | 용도                                                     |
| ----------------- | ------------------------------------------------------ |
| `model`           | Veo model ID입니다. API 레퍼런스 예제에서는 `veo3.1-fast`를 사용합니다.  |
| `prompt`          | 비디오 작업을 위한 텍스트 프롬프트(Prompt)입니다.                        |
| `seconds`         | 길이를 지정하는 form 필드입니다. 레퍼런스 문서에는 `4`, `6`, `8`이 나와 있습니다. |
| `size`            | `1280x720`와 같은 정확한 `WxH` 크기입니다.                        |
| `input_reference` | image-to-video용 선택적 첫 프레임 이미지 파일입니다.                   |

## 문제 해결 / FAQ

<AccordionGroup>
  <Accordion title="content type 문제로 요청이 실패합니다">
    multipart form data를 보내세요. Veo 생성 요청을 JSON으로 보내지 마세요.
  </Accordion>

  <Accordion title="폴링이 예상보다 오래 걸립니다">
    제한된 폴링 루프를 사용하고, task ID를 저장하며, 웹 요청을 블로킹하는 대신 애플리케이션에서 pending 상태를 표시하세요.
  </Accordion>

  <Accordion title="비용은 어떻게 제어해야 하나요">
    짧은 길이, 단일 task, 그리고 허용 가능한 가장 작은 크기부터 시작하세요. task 수를 확장하기 전에 계정 quota와 비용 추정을 활용하세요.
  </Accordion>
</AccordionGroup>

## 다음 단계

* [Veo 3 비디오 생성 API 레퍼런스](/api/video/veo3/create)를 읽어보세요.
* [Veo 3 비디오 조회](/api/video/veo3/retrieve)로 폴링하세요.
* [Models](/ko/overview/models)에서 Veo 비디오 모델을 찾아보세요.
* [비디오 생성을 위한 폴링과 웹훅 사용](/ko/guides/webhook-and-polling-for-video-generation)을 검토하세요.
* [모델 호출 전에 요청 비용 추정](/ko/guides/how-to-estimate-cost-before-calling-a-model)으로 task 비용을 추정하세요.