> ## 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.

# 图生视频

> 从图片、首帧或参考图提交视频生成任务

图生视频用于基于商品图、人物图、首帧、参考图或素材图生成动态视频。当前属于受控开放能力，输入格式会随模型差异变化。

<Warning>不要假设所有视频模型都支持图生视频。只有模型文档明确支持图片输入时，才传图片字段。</Warning>

## 常见输入形态

| 输入形态     | 说明                       |
| -------- | ------------------------ |
| 单张参考图    | 基于一张商品图、人物图或首帧生成视频       |
| 首尾帧      | 用第一帧和最后一帧控制动作变化          |
| 多参考图     | 用多张图保持人物、商品或风格一致         |
| 视频 remix | 基于已有视频继续生成或变化，属于更受控的高级能力 |

## 字段口径

| 字段                     | 可能格式            | 说明                        |
| ---------------------- | --------------- | ------------------------- |
| `model`                | string          | 视频模型名                     |
| `prompt`               | string          | 动作、镜头、场景和风格描述             |
| `input_reference`      | file            | OpenAI / Sora 兼容入口常见参考图字段 |
| `image`                | URL 或 Base64    | Tapapi 任务兼容入口或供应商兼容入口常见字段 |
| `metadata`             | object          | 首尾帧、多参考图、比例、负面提示词等私有参数    |
| `seconds` / `duration` | string / number | 目标时长，具体字段看模型              |

同一个能力在不同模型里可能字段不同。正式接入时，以具体模型页和控制台示例为准。

<Note>`input_reference` 更偏 OpenAI / Sora 兼容入口；`image`、首尾帧、多参考图通常属于具体供应商或任务兼容字段。没有模型页确认时，不要自行组合字段。</Note>

## 参考图请求示例

```bash theme={null}
curl https://tapapi.ai/v1/videos \
  -H "Authorization: Bearer $TAPAPI_API_KEY" \
  -F "model=your-video-model" \
  -F "prompt=Make the product slowly rotate with soft studio lighting, clean ecommerce style" \
  -F "seconds=5" \
  -F "input_reference=@product.jpg"
```

如果模型文档要求使用 URL 或 Base64，可能是下面这种 JSON 任务格式：

```json theme={null}
{
  "model": "your-video-model",
  "prompt": "A product hero video with a slow camera push-in",
  "image": "https://example.com/product.jpg",
  "duration": 5,
  "metadata": {
    "aspect_ratio": "16:9"
  }
}
```

## 图片素材要求

| 项   | 建议                     |
| --- | ---------------------- |
| 清晰度 | 主体清楚，避免低清、强压缩和水印       |
| 构图  | 主体不要贴边，留出运动空间          |
| 背景  | 商品图优先干净背景，人物图避免复杂遮挡    |
| 权限  | 确认你有权上传和生成该素材          |
| 隐私  | 不上传未授权的人脸、证件、合同、客户隐私图片 |

## 常见失败原因

| 现象    | 可能原因                     |
| ----- | ------------------------ |
| 参数错误  | 模型不支持该图片字段、时长或比例         |
| 任务失败  | 图片审核失败、主体不清晰、上游生成失败      |
| 结果不稳定 | prompt 过于抽象、动作和镜头冲突      |
| 取不到视频 | 任务未完成、输出 URL 过期、业务侧未及时转存 |

图生视频一定要保存原始业务任务、输入图版本、`task_id` 和最终输出地址，方便复现和对账。

生产日志还应保存 `X-Oneapi-Request-Id`、模型名、图片来源、图片下载/上传状态、任务最终 `status` 和错误对象。