# 威尔 3.1 API Documentation

> 升级版AI视频模型，提供逼真的动作生成、延长视频时长、多图参考控制及同步原生音频输出，支持1080p画质。

## Overview

This document describes how to call the **威尔 3.1** API.

- **Model / path slug**: `video/veo`
- **Task type**: `async` (`sync` = synchronous, `async` = create task then poll / callback)
- **HTML docs**: `/doc/14`

## Authentication

All API requests require your platform API key as the query parameter `key`:

```
?key=YOUR_API_KEY
```

Get API Key:
1. Sign in to the console
2. Open [API Key Management](/user/key) and create or copy your key
3. Append `key=YOUR_API_KEY` to the request URL (or pass it in form/JSON when the endpoint accepts it)

---

## API Information

- **URL**: `POST https://apis.xiaobao.ink/api/video/veo`
- **Content-Type**: `application/json` (request body commonly `application/json` or `application/x-www-form-urlencoded` for POST)
- **HTTP Method**: `POST`

### Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `prompt` | Yes | 描述所需视频内容的文本提示词。 |
| `imageUrls` | Yes | 图片链接列表（图片生成视频模式使用）。支持1张或2张图片 |
| `model` | Yes | 选择使用的模型类型。 可用选项: veo3, veo3_fast |
| `watermark` | Yes | 水印文本。如果提供，将在生成的视频上添加水印 |
| `callBackUrl` | No | 用于接收视频生成任务完成更新的URL地址。可选但推荐在生产环境中使用。 |
| `aspectRatio` | No | 视频的宽高比。用于指定生成视频的尺寸比例。可选值：16:9, 9:16, Auto |
| `seeds` | No | (可选) 随机种子参数，用于控制生成内容的随机性。取值范围为10000-99999。相同的种子会生成相似的视频内容，不同的种子会生成不同的视频内容。不填写时系统自动分配。 |
| `enableTranslation` | Yes | true 是否启用提示词翻译为英文。当设置为 true 时，系统会自动将提示词翻译为英文后再进行视频生成，以获得更好的生成效果。默认值为 true。 |
| `generationType` | No | 视频生成模式（可选）。指定不同的视频生成方式： |

> **Note**: `key` (API key) is required for authenticated calls even if omitted from the parameter list above.

### Request Example

```
https://apis.xiaobao.ink/api/video/veo?key=你的密钥
```

## Details

## 请求HEADER：

| 名称 | 值 |
| --- | --- |
| Content-Type | application/json |

## 请求参数说明：

| 名称 | 必填 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- | --- |
| prompt | 是 | string | A dog playing in a park | 描述所需视频内容的文本提示词。 |
| imageUrls | 是 | string | [  "http://example.com/image1.jpg",  "http://example.com/image2.jpg" ] | 图片链接列表（图片生成视频模式使用）。支持1张或2张图片： |
| model | 否 | string | veo3_fast | 选择使用的模型类型。 默认：veo3_fast 可用选项:veo3,veo3_fast |
| generationType | 否 | string | TEXT_2_VIDEO | 视频生成模式（可选）。可用选项:TEXT_2_VIDEO,FIRST_AND_LAST_FRAMES_2_VIDEO,REFERENCE_2_VIDEO 指定不同的视频生成方式TEXT_2_VIDEO：文生视频 - 仅使用文本提示词生成视频 FIRST_AND_LAST_FRAMES_2_VIDEO：首尾帧生视频 - 灵活的图片到视频生成模式 传1张图片：基于该图片生成视频 传2张图片：第一张作为首帧，第二张作为尾帧，生成过渡视频 REFERENCE_2_VIDEO：参考图生视频 - 基于参考图片生成视频，需要在 imageUrls 中提供1-3张图片（至少1张，最多3张） |
| watermark | 否 | string | 销豹AI | 水印文本。如果提供，将在生成的视频上添加水 |
| aspectRatio | 否 | string | 16:9 | 可用选项:16:9,9:16,Auto |
| seeds | 否 | integer | 12345 | 必填范围: 10000 |
| callBackUrl | 是 | string | http://your-callback-url.com/complete | 用于接收视频生成任务完成更新的URL地址。可选但推荐在生产环境中使用。 |

## 返回参数说明：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| code | int | 状态码 |
| msg | string | 状态信息 |
| data | string | 请求结果数据集 |
| - taskId | string | veo_task_abcdef123456 任务ID |
| debug | string/array | 调试数据 |
| exec_time | float | 执行耗时 |
| user_ip | string | 客户端IP |

## Response Example

```
{  "code": 200,  "msg": "success",  "data": {    "taskId": "veo_task_abcdef123456"  }}成功回调：{  "code": 200,  "msg": "Veo3.1 视频生成成功。",  "data": {    "taskId": "veo_task_abcdef123456",    "info": {      "resultUrls": ["http://example.com/video1.mp4"],      "originUrls": ["http://example.com/original_video1.mp4"],      "resolution": "1080p"    },    "fallbackFlag": false  }}
```

## Error Codes

| 错误码 | 类型 | 说明 |
| --- | --- | --- |
| 200 | int | 成功 - 请求已成功处理 |
| 400 | int | 1080P正在处理中。预计1-2分钟后准备就绪。请稍后再次查看。 |
| 401 | int | 未授权 - 认证凭据缺失或无效 |
| 402 | int | 积分不足 - 账户没有足够的积分执行操作 |
| 404 | int | 未找到 - 请求的资源或端点不存在 |
| 422 | int | 验证错误 - 请求参数验证失败。当未开启托底且生成失败时，错误信息格式为：Your request was rejected by Flow(原始错误信息). You may consider using our other fallback channels, which are likely to succeed. Please refer to the documentation. |
| 429 | int | 请求限制 - 已超过该资源的请求限制 |
| 455 | int | 服务不可用 - 系统正在进行维护 |
| 500 | int | 服务器错误 - 处理请求时发生意外错误 |
| 501 | int | 生成失败 - 视频生成任务失败 |
| 505 | int | 功能禁用 - 请求的功能当前已禁用 |

## Usage Flow

1. **Create Task**: Call this API with your `key` and required parameters
2. **Get Task ID**: Read the task id from the response
3. **Wait for Results**: Use the notify/callback URL if provided, or poll the related query endpoint
4. **Get Results**: When the task succeeds, read result URLs / payload from the response

---

_Generated for AI / LLM consumption. Source of truth: `api_list` (same as HTML `/doc/{id}`)._