> ## 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 端點，並將最終資產 URL 或檔案儲存到你自己的系統中。

## 先決條件

* 已儲存在 `COMETAPI_KEY` 中的 CometAPI API key
* Python 3.10+ 搭配 `requests`，或 Node.js 18+
* 用於輪詢的伺服器端工作執行器

## API key、基礎 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 token 進行驗證：

```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 或檔案詳細資訊。

初次測試時，請使用較短的時長與最小但仍實用的尺寸。當你的應用程式需要保留資產時，請將已完成的資產移至你自己的儲存空間。

## 常用參數

| 參數                | 用途                                     |
| ----------------- | -------------------------------------- |
| `model`           | Veo model ID。API 參考範例使用 `veo3.1-fast`。 |
| `prompt`          | 影片任務的文字 Prompt。                        |
| `seconds`         | 持續時間表單欄位。參考文件記載 `4`、`6` 和 `8`。         |
| `size`            | 精確的 `WxH` 尺寸，例如 `1280x720`。            |
| `input_reference` | 可選的首幀圖片檔案，用於 image-to-video。           |

## 疑難排解 / 常見問題

<AccordionGroup>
  <Accordion title="因內容類型問題導致請求失敗">
    請傳送 multipart form data。不要將 Veo 建立請求作為 JSON 傳送。
  </Accordion>

  <Accordion title="輪詢花費的時間比預期更長">
    請使用有界的輪詢迴圈、儲存 task ID，並在你的應用程式中顯示等待中的狀態，而不是阻塞 web 請求。
  </Accordion>

  <Accordion title="我該如何控制成本">
    先從較短的持續時間、單一任務，以及可接受的最小尺寸開始。在擴大任務數量之前，請使用帳戶配額與成本估算。
  </Accordion>
</AccordionGroup>

## 後續步驟

* 閱讀[建立 Veo 3 影片 API 參考](/api/video/veo3/create)。
* 使用[擷取 Veo 3 影片](/api/video/veo3/retrieve)進行輪詢。
* 在[Models](/zh-Hant/overview/models)中尋找 Veo 影片模型。
* 參閱[對影片生成使用輪詢與 webhooks](/zh-Hant/guides/webhook-and-polling-for-video-generation)。
* 使用[在呼叫 model 之前估算請求成本](/zh-Hant/guides/how-to-estimate-cost-before-calling-a-model)來估算任務成本。