# see2ai_video_generation_v1

> AI 视频生成服务，基于 SEE2AI 官方视频生成引擎 模型，支持文生视频和图生视频。

## 📖 接入指引

**Endpoint**: `POST /api/v1/actions/see2ai_video_generation_v1`

**认证方式**: Bearer Token (租户 API Key)

> **⚠️ 重要提示**
> 
> 本 API 是 SEE2AI 平台封装后的接口，**参数格式与上游官方（如火山引擎、OpenAI等）API 不同**。
> 请直接使用下方 Schema 中定义的参数，无需参考官方文档。
> 
> *例如：*
> *- 文本模型参数可能是 `query` 而不是 `messages` 数组*
> *- 视频模型参数可能是 `brief` (创意简报) 而不是复杂的配置项*

## 📥 输入参数 (Input Schema)

```json
{
  "description": "SEE2AI 官方视频生成引擎 AI视频生成输入参数模型",
  "properties": {
    "model_name": {
      "default": "doubao-seedance-2-0-260128",
      "description": "视频生成模型版本（用户可显式选择）：doubao-seedance-2-0-260128 = 标准版（画质优先，默认）；doubao-seedance-2-0-fast-260128 = 快速版（速度/成本优先，价格约为标准版 80%）。",
      "enum": [
        "doubao-seedance-2-0-260128",
        "doubao-seedance-2-0-fast-260128"
      ],
      "title": "Model Name",
      "type": "string"
    },
    "prompt": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "描述想要生成的视频的文本提示词。",
      "title": "Prompt"
    },
    "non_face_image_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "不包含真人脸部的参考图片 URL（单图），适用于场景、商品、风景、建筑等任意非人脸图片。如果图片包含真人脸部，请改用 face_image_url 参数。只接受公网 URL。",
      "title": "Non Face Image Url"
    },
    "non_face_image_urls": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "不包含真人脸部的参考图片 URL 列表。如果图片包含真人脸部，请改用 face_image_url 参数。",
      "title": "Non Face Image Urls"
    },
    "face_image_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "包含真人脸部的图片 URL。如果图片中有真人面孔，请使用此参数；不包含真人脸部的图片请改用 non_face_image_url。系统会自动将人脸图片上传至素材库完成合规验证。",
      "title": "Face Image Url"
    },
    "video_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "输入的参考视频 URL。",
      "title": "Video Url"
    },
    "video_urls": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "输入的参考视频 URL 列表（最多3段）。",
      "title": "Video Urls"
    },
    "audio_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "输入的参考音频 URL。",
      "title": "Audio Url"
    },
    "audio_urls": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "输入的参考音频 URL 列表（最多3段）。",
      "title": "Audio Urls"
    },
    "first_frame_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "首帧图片 URL。",
      "title": "First Frame Url"
    },
    "last_frame_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "尾帧图片 URL。",
      "title": "Last Frame Url"
    },
    "duration": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": 5,
      "description": "生成视频的时长（秒），支持 4~15 或 -1 让模型自动决定时长。",
      "title": "Duration"
    },
    "resolution": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": "720p",
      "description": "分辨率，支持 720p 或 480p。",
      "title": "Resolution"
    },
    "aspect_ratio": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": "adaptive",
      "description": "生成视频的宽高比。",
      "examples": [
        "adaptive",
        "16:9",
        "9:16",
        "1:1",
        "21:9",
        "4:3",
        "3:4"
      ],
      "title": "Aspect Ratio"
    },
    "watermark": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": false,
      "description": "是否添加水印。",
      "title": "Watermark"
    },
    "generate_audio": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": true,
      "description": "是否生成同步音频。开启后模型会生成与画面同步的人声、音效和背景音乐。",
      "title": "Generate Audio"
    },
    "enable_web_search": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": false,
      "description": "是否开启联网搜索增强生成。",
      "title": "Enable Web Search"
    },
    "force_asset_upload": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": false,
      "description": "全局兜底开关：强制将所有图片/视频 URL 上传至素材库以绕过敏感度机审。注意：开启后会导致严重的性能下降（所有大文件需重新下载并上传）并产生高额的额外 Token 计费，除非普通直传频繁失败，否则强烈建议保持 False。",
      "title": "Force Asset Upload"
    },
    "sync": {
      "default": true,
      "description": "是否同步等待结果。如果为 False，则只提交任务并立即返回 task_id，后续可通过 /status/{task_id} 接口查询进度。",
      "title": "Sync",
      "type": "boolean"
    }
  },
  "title": "VideoGenerationInput",
  "type": "object"
}
```

### 参数说明

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `model_name` | string | ❌ 否 | `doubao-seedance-2-0-260128` | 视频生成模型版本（用户可显式选择）：doubao-seedance-2-0-260128 = 标准版（画质优先，默认）；doubao-seedance-2-0-fast-260128 = 快速版（速度/成本优先，价格约为标准版 80%）。 |
| `prompt` | string | ❌ 否 | `-` | 描述想要生成的视频的文本提示词。 |
| `non_face_image_url` | string | ❌ 否 | `-` | 不包含真人脸部的参考图片 URL（单图），适用于场景、商品、风景、建筑等任意非人脸图片。如果图片包含真人脸部，请改用 face_image_url 参数。只接受公网 URL。 |
| `non_face_image_urls` | string | ❌ 否 | `-` | 不包含真人脸部的参考图片 URL 列表。如果图片包含真人脸部，请改用 face_image_url 参数。 |
| `face_image_url` | string | ❌ 否 | `-` | 包含真人脸部的图片 URL。如果图片中有真人面孔，请使用此参数；不包含真人脸部的图片请改用 non_face_image_url。系统会自动将人脸图片上传至素材库完成合规验证。 |
| `video_url` | string | ❌ 否 | `-` | 输入的参考视频 URL。 |
| `video_urls` | string | ❌ 否 | `-` | 输入的参考视频 URL 列表（最多3段）。 |
| `audio_url` | string | ❌ 否 | `-` | 输入的参考音频 URL。 |
| `audio_urls` | string | ❌ 否 | `-` | 输入的参考音频 URL 列表（最多3段）。 |
| `first_frame_url` | string | ❌ 否 | `-` | 首帧图片 URL。 |
| `last_frame_url` | string | ❌ 否 | `-` | 尾帧图片 URL。 |
| `duration` | string | ❌ 否 | `5` | 生成视频的时长（秒），支持 4~15 或 -1 让模型自动决定时长。 |
| `resolution` | string | ❌ 否 | `720p` | 分辨率，支持 720p 或 480p。 |
| `aspect_ratio` | string | ❌ 否 | `adaptive` | 生成视频的宽高比。 |
| `watermark` | string | ❌ 否 | `False` | 是否添加水印。 |
| `generate_audio` | string | ❌ 否 | `True` | 是否生成同步音频。开启后模型会生成与画面同步的人声、音效和背景音乐。 |
| `enable_web_search` | string | ❌ 否 | `False` | 是否开启联网搜索增强生成。 |
| `force_asset_upload` | string | ❌ 否 | `False` | 全局兜底开关：强制将所有图片/视频 URL 上传至素材库以绕过敏感度机审。注意：开启后会导致严重的性能下降（所有大文件需重新下载并上传）并产生高额的额外 Token 计费，除非普通直传频繁失败，否则强烈建议保持 False。 |
| `sync` | boolean | ❌ 否 | `True` | 是否同步等待结果。如果为 False，则只提交任务并立即返回 task_id，后续可通过 /status/{task_id} 接口查询进度。 |

## 📤 输出结果 (Output Schema)

```json
{
  "description": "SEE2AI 官方视频生成引擎 AI视频生成输出参数模型",
  "properties": {
    "input_tokens": {
      "default": 0,
      "description": "输入消耗的词元数量",
      "title": "Input Tokens",
      "type": "integer"
    },
    "output_tokens": {
      "default": 0,
      "description": "输出消耗的词元数量",
      "title": "Output Tokens",
      "type": "integer"
    },
    "total_tokens": {
      "default": 0,
      "description": "总消耗的词元数量",
      "title": "Total Tokens",
      "type": "integer"
    },
    "model": {
      "default": "",
      "description": "实际使用的模型名称（由各 action 显式填写）",
      "title": "Model",
      "type": "string"
    },
    "source": {
      "default": "",
      "description": "模型提供商（由各 action 显式填写）",
      "title": "Source",
      "type": "string"
    },
    "cost_points": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "预先计算的扣费词元（如果插件内部已经计算好费用，则直接使用此值，忽略基于词元的计算）",
      "title": "Cost Points"
    },
    "result_urls": {
      "default": [],
      "description": "生成的视频 URL 列表",
      "items": {
        "type": "string"
      },
      "title": "Result Urls",
      "type": "array"
    },
    "task_id": {
      "description": "生成任务的 ID",
      "title": "Task Id",
      "type": "string"
    },
    "cost_time": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "生成耗时（毫秒）",
      "title": "Cost Time"
    },
    "state": {
      "description": "任务最终状态",
      "title": "State",
      "type": "string"
    },
    "provider_config_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "供应商配置 ID（用于追溯）",
      "title": "Provider Config Id"
    },
    "error_message": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "失败时的错误信息",
      "title": "Error Message"
    },
    "warnings": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "非阻断性优化建议列表（参数合法但非最优实践时由前置校验器产出，方便调用方后续优化）。",
      "title": "Warnings"
    }
  },
  "required": [
    "task_id",
    "state"
  ],
  "title": "VideoGenerationOutput",
  "type": "object"
}
```

### 输出字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `input_tokens` | integer | 输入消耗的词元数量 |
| `output_tokens` | integer | 输出消耗的词元数量 |
| `total_tokens` | integer | 总消耗的词元数量 |
| `model` | string | 实际使用的模型名称（由各 action 显式填写） |
| `source` | string | 模型提供商（由各 action 显式填写） |
| `cost_points` | string | 预先计算的扣费词元（如果插件内部已经计算好费用，则直接使用此值，忽略基于词元的计算） |
| `result_urls` | array | 生成的视频 URL 列表 |
| `task_id` | string | 生成任务的 ID |
| `cost_time` | string | 生成耗时（毫秒） |
| `state` | string | 任务最终状态 |
| `provider_config_id` | string | 供应商配置 ID（用于追溯） |
| `error_message` | string | 失败时的错误信息 |
| `warnings` | string | 非阻断性优化建议列表（参数合法但非最优实践时由前置校验器产出，方便调用方后续优化）。 |

## 💡 调用示例

### cURL 示例

```bash
curl -X POST "https://see2ai.com/api/v1/actions/see2ai_video_generation_v1" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer sk-your-tenant-api-key" \
     -d '{
  "model_name": "示例值",
  "prompt": "示例值",
  "non_face_image_url": "https://example.com/image.jpg",
  "face_image_url": "https://example.com/image.jpg",
  "video_url": "https://example.com/image.jpg",
  "audio_url": "https://example.com/image.jpg",
  "first_frame_url": "https://example.com/image.jpg",
  "last_frame_url": "https://example.com/image.jpg",
  "duration": "示例值",
  "resolution": "示例值",
  "aspect_ratio": "示例值",
  "watermark": "示例值",
  "generate_audio": "示例值",
  "enable_web_search": "示例值",
  "force_asset_upload": "示例值",
  "sync": false
}'
```

### Python 示例

```python
import requests

API_KEY = "sk-your-tenant-api-key"
ENDPOINT = "https://see2ai.com/api/v1/actions/see2ai_video_generation_v1"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

payload = {
  "model_name": "\u793a\u4f8b\u503c",
  "prompt": "\u793a\u4f8b\u503c",
  "non_face_image_url": "https://example.com/image.jpg",
  "face_image_url": "https://example.com/image.jpg",
  "video_url": "https://example.com/image.jpg",
  "audio_url": "https://example.com/image.jpg",
  "first_frame_url": "https://example.com/image.jpg",
  "last_frame_url": "https://example.com/image.jpg",
  "duration": "\u793a\u4f8b\u503c",
  "resolution": "\u793a\u4f8b\u503c",
  "aspect_ratio": "\u793a\u4f8b\u503c",
  "watermark": "\u793a\u4f8b\u503c",
  "generate_audio": "\u793a\u4f8b\u503c",
  "enable_web_search": "\u793a\u4f8b\u503c",
  "force_asset_upload": "\u793a\u4f8b\u503c",
  "sync": false
}

response = requests.post(ENDPOINT, json=payload, headers=headers)
result = response.json()

print(f"结果：{result}")
```

## 💰 计费说明

> 按次调用计费

**注意**: 所有费用都以词元为单位，系统会自动从租户余额中扣除。

## ⚠️ 常见错误码

| HTTP 状态码 | 错误原因 | 解决方案 |
| --- | --- | --- |
| `400` | 参数错误，如缺失 prompt 或无效的时长 | 请稍后重试 |
| `401` | API Key 无效或未授权 | 检查 API Key 是否正确，或联系管理员充值 |
| `402` | 账号余额不足 | 请稍后重试 |
| `429` | 请求超限，达到速率限制 | 降低请求频率，或联系管理员调整限流配置 |
| `500` | 上游服务器内部错误或生成失败 | 稍后重试，如持续失败请联系技术支持 |
| `504` | 任务轮询超时（例如任务处理超过指定时间限制） | 请稍后重试 |

## 📞 技术支持

- **文档问题**: 查看 [SEE2AI 官方文档](https://see2ai.com/docs)
- **API 状态**: 访问 [服务状态页面](https://see2ai.com/status)
- **问题反馈**: 联系技术支持团队

---

**API 版本**: see2ai_video_generation_v1
**最后更新**: 2026-03-23