> ## 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，轮询获取端点，并将最终资源 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 视频生成是异步的。创建端点接受 multipart form data，并立即返回一个任务 ID。持续轮询获取端点，直到任务达到终态状态，然后从完成响应中持久化最终视频 URL 或文件详情。

首次测试时，请使用较短时长和满足需求的最小尺寸。当你的应用需要长期保留时，请将已完成的资源转移到你自己的存储中。

## 常用参数

| 参数                | 用途                                     |
| ----------------- | -------------------------------------- |
| `model`           | Veo model ID。API 参考示例使用 `veo3.1-fast`。 |
| `prompt`          | 视频任务的文本 Prompt。                        |
| `seconds`         | 时长表单字段。参考文档记录了 `4`、`6` 和 `8`。          |
| `size`            | 精确的 `WxH` 尺寸，例如 `1280x720`。            |
| `input_reference` | 可选的首帧图像文件，用于图生视频。                      |

## 故障排查 / 常见问题

<AccordionGroup>
  <Accordion title="请求因内容类型问题而失败">
    发送 multipart 表单数据。不要将 Veo 创建请求作为 JSON 发送。
  </Accordion>

  <Accordion title="轮询耗时比预期更长">
    使用有界轮询循环，存储任务 ID，并在你的应用中显示待处理状态，而不是阻塞一个 Web 请求。
  </Accordion>

  <Accordion title="我应该如何控制成本">
    从较短时长、单个任务和可接受的最小尺寸开始。在扩大任务数量之前，先使用账户配额和成本估算。
  </Accordion>
</AccordionGroup>

## 后续步骤

* 阅读[创建 Veo 3 视频 API 参考](/api/video/veo3/create)。
* 使用[获取 Veo 3 视频](/api/video/veo3/retrieve)进行轮询。
* 在[模型](/zh-Hans/overview/models)中查找 Veo 视频模型。
* 查看[对视频生成使用轮询和 webhook](/zh-Hans/guides/webhook-and-polling-for-video-generation)。
* 使用[在调用模型前估算请求成本](/zh-Hans/guides/how-to-estimate-cost-before-calling-a-model)估算任务成本。