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

# 文生视频

> 从文本 prompt 提交视频生成任务

文生视频用于把文本描述转成短视频。当前按受控开放能力处理：只有控制台可见、价格已发布、模型文档明确支持的模型，才适合接入生产。

## 推荐流程

```text theme={null}
POST /v1/videos
  -> 保存返回的 id / task_id
  -> GET /v1/videos/{task_id}
  -> completed 后 GET /v1/videos/{task_id}/content
```

<Note>`/v1/videos` 是后续主推的 OpenAI / Sora 兼容视频入口。`/v1/video/generations` 属于 Tapapi 任务兼容入口，适合受控场景或供应商适配，不建议普通接入优先使用。</Note>

## 请求字段

| 字段         | 类型     | 说明                            |
| ---------- | ------ | ----------------------------- |
| `model`    | string | 视频模型名，必须是控制台可见模型              |
| `prompt`   | string | 视频描述，建议包含主体、动作、镜头、场景和风格       |
| `seconds`  | string | 视频时长，例如 `"5"` 或 `"8"`，支持范围看模型 |
| `size`     | string | 视频尺寸或比例，是否支持看模型               |
| `metadata` | object | 模型私有参数，仅在模型文档明确说明时使用          |

不同模型可能使用 `duration`、`aspect_ratio`、`quality` 等私有字段。不要把某个模型的私有字段直接复用到所有视频模型。

## 请求示例

```bash theme={null}
curl https://tapapi.ai/v1/videos \
  -H "Authorization: Bearer $TAPAPI_API_KEY" \
  -F "model=your-video-model" \
  -F "prompt=A product shot video of a silver necklace rotating on a clean white background" \
  -F "seconds=5"
```

返回值会包含任务 ID 和初始状态，字段可能随兼容格式略有差异：

```json theme={null}
{
  "id": "task_xxx",
  "object": "video",
  "model": "your-video-model",
  "status": "queued",
  "progress": 0,
  "seconds": "5"
}
```

提交成功后请同时保存响应头 `X-Oneapi-Request-Id`。它用于定位“提交请求”本身；后续查询任务时还要保存查询请求自己的 request id。

## Prompt 建议

| 目标 | 写法                       |
| -- | ------------------------ |
| 主体 | 明确人物、商品、场景或镜头主体          |
| 动作 | 写清楚主体怎么动、镜头怎么动           |
| 时长 | 不要在 prompt 里写超过模型支持范围的时长 |
| 风格 | 写可执行的风格词，不要堆太多冲突描述       |
| 禁忌 | 负面提示词是否支持取决于模型，不要默认可用    |

示例：

```text theme={null}
A 5-second ecommerce product video of a silver necklace slowly rotating on a white background, soft studio lighting, clean reflections, no text overlay.
```

## 生产注意

* 文生视频耗时通常明显高于文本和图片接口
* 视频任务成本更高，先做小流量验证
* 不要用同步 HTTP 等待完整生成结果
* 保存 `task_id`，用它做轮询、对账和客服排障
* 任务成功后尽快转存输出视频
* 轮询时按最终 `status` 决定是否补跑，不要因为一次查询超时就重复提交新任务
* `seconds`、`size`、`duration`、`aspect_ratio` 等字段是否可用以具体模型为准

任务轮询和内容获取见 [任务与输出](/video-generation/tasks-and-output)。