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

# Veo3

> Google Veo3 视频生成模型 API 接口

<Info>
  `veo3` 底层调用的是 Google 的 Veo3 视频生成模型，支持文生视频和图生视频。
</Info>

## 查询任务状态

提交任务后，可通过统一的查询端点查看任务进度并获取生成结果：

<Card title="获取任务详情" icon="magnifying-glass" href="/api-reference/common/get-task-detail">
  了解如何查询任务状态并获取生成结果
</Card>

<Tip>
  生产环境中，建议使用 `callback_url`
  参数接收生成完成的自动通知，而非轮询状态端点。
</Tip>

## 授权

<ParamField header="Authorization" type="string" required>
  Bearer Token 认证。格式：`Bearer sk-xxxxxx`

  <Expandable defaultOpen title="详细说明">
    * 获取 API Key：访问 [API Key 管理页面](https://ruxa.ai/dashboard/api-keys) 获取您的 API Key

    * 使用方法：在请求头中添加 `Authorization: Bearer YOUR_API_KEY`

    * 注意事项：请妥善保管您的 API Key，切勿泄露给他人

    * 若怀疑 API Key 泄露，请立即在管理页面重置
  </Expandable>
</ParamField>

## 请求体

请求体格式为 `application/json`。

<ParamField body="model" type="string" required default="veo3">
  模型名称，固定为 `veo3`
</ParamField>

<ParamField body="callback_url" type="string">
  任务完成后的回调地址。系统会向该 URL POST 任务状态与结果。

  示例：`https://your-domain.com/api/callback`
</ParamField>

<ParamField body="input" type="object" required>
  生成任务的输入参数

  <Expandable defaultOpen title="子属性">
    <ParamField body="input.prompt" type="string" required>
      用于视频生成的文本提示词

      <Expandable defaultOpen title="示例">
        ```
        "让画面动起来"
        ```
      </Expandable>
    </ParamField>

    <ParamField body="input.input_reference_url" type="string">
      参考图片的 URL 地址（用于图生视频场景）

      <Expandable defaultOpen title="示例">
        ```
        "https://example.com/your-image.png"
        ```
      </Expandable>
    </ParamField>

    <ParamField body="input.seconds" type="string" default="10">
      生成视频的时长（秒）
    </ParamField>

    <ParamField body="input.aspect_ratio" type="enum<string>" default="16:9">
      生成视频的宽高比

      可用选项：`16:9`, `9:16`, `1:1`
    </ParamField>

    <ParamField body="input.enhance_prompt" type="boolean" default="true">
      是否增强提示词
    </ParamField>

    <ParamField body="input.enable_upsample" type="boolean" default="false">
      是否启用超分辨率
    </ParamField>
  </Expandable>
</ParamField>

## 响应

<ResponseField name="code" type="integer" required>
  响应状态码

  <Expandable defaultOpen title="状态码说明">
    * `200`: 成功 - 请求已处理完成

    * `401`: 未授权 - 身份验证凭据缺失或无效

    * `402`: 积分不足 - 账户积分不足以执行该操作

    * `404`: 未找到 - 请求的资源或端点不存在

    * `422`: 验证错误 - 请求参数未通过校验

    * `429`: 速率限制 - 已超出该资源的请求频次限制

    * `500`: 服务器错误 - 处理请求时发生意外故障
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string" required>
  响应消息，请求失败时为错误描述
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable defaultOpen title="子属性">
    <ResponseField name="data.taskId" type="string" required>
      任务 ID，用于查询任务状态
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.ruxa.ai/api/v1/tasks/create \
    --header 'Authorization: Bearer sk-xxxxxx' \
    --header 'Content-Type: application/json' \
    --data '{
      "callback_url": "https://your-domain.com/api/callback",
      "input": {
        "prompt": "让画面动起来",
        "input_reference_url": "https://example.com/your-image.png",
        "seconds": "10",
        "aspect_ratio": "16:9",
        "enhance_prompt": true,
        "enable_upsample": false
      },
      "model": "veo3"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
      "taskId": "task_veo3_1766304530229_cf4dafd2"
    }
  }
  ```
</ResponseExample>