feat(*): 插件中心与模型协议 - 完善声明式协议运行时并增加功能开放控制
This commit is contained in:
ddCat
46
backend/internal/protocol/docs/agnes-video.md
Normal file
46
backend/internal/protocol/docs/agnes-video.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# Agnes 视频协议（当前不可用）
|
||||
|
||||
Agnes 作为内置占位插件保留，是为了让历史模型配置能显示明确的不可用原因，而不是静默消失。当前仓库没有可验证的官方接口、鉴权、模型、轮询和响应资料，因此插件被强制禁用，也不可安装或选择。
|
||||
|
||||
## 接口与当前状态
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
创建、轮询、取消路径均为空。调用 `BuildCreate` 会返回 `UnavailableError`：`未提供可验证的官方请求、鉴权、轮询和响应协议资料`。页面展示该条目不代表可以发送任务。
|
||||
|
||||
## 模型与能力状态
|
||||
|
||||
当前没有任何经过验证的模型 ID、能力范围或计费规则。任何 Agnes 模型名都不可提交；只有取得官方模型目录并完成真实账户验证后，才能写入渠道模型配置。
|
||||
|
||||
## 参数与字段状态
|
||||
|
||||
当前 metadata 没有参数映射，创建请求也不存在。`model`、`prompt`、参考素材、时长、比例、分辨率、音频和水印均不得推测或透传。
|
||||
|
||||
## 启用前必须补齐的事实
|
||||
|
||||
| 项目 | 必须取得的证据 | 验收方式 |
|
||||
| --- | --- | --- |
|
||||
| 服务入口 | 官方 Base URL、版本、区域 | 官方文档链接和最小健康探测 |
|
||||
| 鉴权 | Header、Token/签名算法、权限范围 | 不在 URL/日志泄露密钥的集成测试 |
|
||||
| 模型 | 精确模型 ID、能力和停用策略 | 真实账户模型发现或官方表 |
|
||||
| 创建 | Method、Path、Content-Type、完整字段 | 请求 fixture 与真实 2xx 响应 |
|
||||
| 轮询 | 任务 ID、状态枚举、失败结构 | queued -> running -> completed/failed fixture |
|
||||
| 结果 | 视频 URL、文件接口、有效期 | 下载并存入影策资源的冒烟测试 |
|
||||
| 取消与账务 | 是否支持取消、失败退款语义 | 官方合同与错误场景验证 |
|
||||
|
||||
## 禁止的临时处理
|
||||
|
||||
- 不得根据插件名猜测 `/v1/videos`、模型名或 Bearer 鉴权。
|
||||
- 不得复用其他视频供应商的字段并把 200 响应当兼容。
|
||||
- 不得用空任务 ID、默认成功状态或假 URL 让页面“看起来能用”。
|
||||
- 不得仅在前端隐藏；后端 registry 和写路径必须继续拒绝不可用协议。
|
||||
|
||||
## 未来实现结构
|
||||
|
||||
取得官方资料后，应新增独立 adapter、专属 create/poll/result fixture、错误码映射和一份替换本文的完整文档。若协议实际是已有供应商的别名，应迁移历史配置到明确的 canonical ID，而不是永久保留第二套执行逻辑。
|
||||
|
||||
## 官方资料
|
||||
|
||||
当前未找到可验证且与本插件对应的官方开发者资料。为避免误导，本页不引用搜索聚合、论坛转述或其他同名产品文档。
|
||||
|
||||
{{CONTRACT}}
|
||||
52
backend/internal/protocol/docs/async-audio.md
Normal file
52
backend/internal/protocol/docs/async-audio.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# 异步音频任务兼容协议
|
||||
|
||||
该插件定义一个简化的 OpenAI 风格异步音频合同：JSON 创建任务，轮询任务资源，成功后读取媒体 URL。它不是 OpenAI 官方 Speech API，也不代表某个固定供应商。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/audio/tasks
|
||||
GET {channel_base_url}/v1/audio/tasks/{task_id}
|
||||
Authorization: Bearer <CHANNEL_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型、声音与计费
|
||||
|
||||
模型 ID、任务类型、声音、语言、格式、时长限制、音色克隆权限和计费完全由实现该兼容接口的渠道决定。插件没有供应商白名单；管理员必须用该部署的接口文档校对。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
当前创建正文只包含：
|
||||
|
||||
```json
|
||||
{"model":"YOUR_ASYNC_AUDIO_MODEL","prompt":"低沉克制的男声旁白：风暴即将到来。"}
|
||||
```
|
||||
|
||||
没有映射 `voice`、`format`、`speed`、参考音频、歌词或音乐结构。若模型依赖这些字段，当前插件不适用。
|
||||
|
||||
## 创建、轮询与结果
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/audio/tasks" \
|
||||
-H "Authorization: Bearer <CHANNEL_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model":"YOUR_ASYNC_AUDIO_MODEL","prompt":"雨声环境音，逐渐增强"}'
|
||||
```
|
||||
|
||||
创建响应需包含任务 ID，查询路径使用该 ID。轮询 parser 按音频类型提取 `audios`、`audio_url`、`audioUrl`、`result_url` 或 `url`，不会把音频误写入视频结果。若部署返回其他深层结构，必须增加该渠道 fixture 和明确映射。
|
||||
|
||||
## 错误与安全
|
||||
|
||||
任务不存在、模型不支持、输入过长、声音授权或内容审核失败应原样返回。涉及真人声音克隆时必须确认授权；参考音频和生成链接不得写入公开日志。结果 URL 应尽快转存。
|
||||
|
||||
## 官方资料与边界
|
||||
|
||||
- 本页以影策当前 adapter 为唯一字段事实源。
|
||||
- 渠道部署方必须提供真实的模型、声音、错误码和计费文档；没有这些资料时不能对用户承诺能力。
|
||||
|
||||
{{CONTRACT}}
|
||||
62
backend/internal/protocol/docs/chat-completion.md
Normal file
62
backend/internal/protocol/docs/chat-completion.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# OpenAI Chat Completions
|
||||
|
||||
Chat Completions 是基于 `messages` 的同步或流式文本协议。影策默认把提示词包装成一条 `user` 消息；需要多轮上下文、工具调用或结构化输出时，通过模型扩展参数传入完整 OpenAI 字段。
|
||||
|
||||
## 接口、鉴权与请求模式
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/chat/completions
|
||||
Authorization: Bearer <API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
官方服务的 Base URL 通常以 `/v1` 结尾；在影策中应以渠道实际配置为准。同步请求返回单个 JSON；`stream: true` 时上游返回 SSE，影策文本任务流负责转发和组装事件。
|
||||
|
||||
## 模型与兼容边界
|
||||
|
||||
模型名不会由插件维护白名单，必须填写渠道实际暴露的模型 ID。OpenAI 新项目更推荐 Responses API；现有 Chat Completions 模型和兼容渠道仍可使用本插件。兼容渠道可能只实现字段子集，不能因为路径相同就假定支持工具、视觉输入或 JSON Schema。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
可通过 `extra` 透传 `messages`、`temperature`、`top_p`、`max_tokens`、`stream`、`tools` 和 `response_format`。传入 `extra.messages` 时会替换默认单条消息，而不是追加。
|
||||
|
||||
## 完整请求示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/chat/completions" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "YOUR_MODEL",
|
||||
"messages": [
|
||||
{"role":"system","content":"你是影视分镜助理。"},
|
||||
{"role":"user","content":"把这场雨夜追逐拆成 6 个镜头。"}
|
||||
],
|
||||
"temperature": 0.7
|
||||
}'
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "chatcmpl_xxx",
|
||||
"choices": [{"message":{"role":"assistant","content":"1. 全景……"},"finish_reason":"stop"}],
|
||||
"usage": {"prompt_tokens":32,"completion_tokens":95,"total_tokens":127}
|
||||
}
|
||||
```
|
||||
|
||||
## 响应解析、流式与错误
|
||||
|
||||
同步解析只读取 `choices[0].message.content`，并保留顶层 `usage`。当前解析器不把 `tool_calls` 当文本结果；只有工具调用而没有正文时，应由调用方进入工具回合，不能当作普通文本成功。流式分片、结束标记和断线续传由文本任务 SSE 链路处理，不使用此同步 JSON 解析器硬拼。
|
||||
|
||||
常见失败包括模型不存在、上下文超限、字段不受兼容服务支持、额度或速率限制。应保留上游 HTTP 状态和错误正文，不改写为成功。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [OpenAI Chat Completions API Reference](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
|
||||
- [OpenAI Text generation guide](https://developers.openai.com/api/docs/guides/text)
|
||||
|
||||
{{CONTRACT}}
|
||||
65
backend/internal/protocol/docs/claude-api.md
Normal file
65
backend/internal/protocol/docs/claude-api.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# Claude Messages API
|
||||
|
||||
Claude Messages 使用无状态 `messages` 请求生成内容。影策默认创建一条 `user` 消息、设置 `max_tokens: 4096`，并自动添加 `anthropic-version: 2023-06-01`。系统提示使用顶层 `system`，不能伪装成 `system` 角色消息。
|
||||
|
||||
## 接口、鉴权与版本头
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/messages
|
||||
x-api-key: <API_KEY>
|
||||
anthropic-version: 2023-06-01
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
影策的通用渠道中转也可能以 Bearer 方式连接兼容网关；直连 Anthropic 时必须按官方 `x-api-key` 规则配置渠道。版本头由适配器固定添加，Beta 能力需要额外头部时当前插件不会自动猜测。
|
||||
|
||||
## 模型与兼容边界
|
||||
|
||||
模型 ID 必须使用账户和区域实际可用的 Anthropic 模型名。AWS Bedrock、Google Vertex AI 与 Anthropic 原生 API 的鉴权、路径和模型名不同，不能把原生 Messages 插件直接当作云厂商协议使用，除非中间网关已完成协议转换。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
`extra` 可透传 `max_tokens`、`system`、`messages`、`temperature`、`top_p`、`top_k`、`tools`、`tool_choice` 和 `stream`。`extra.messages` 替换默认消息数组。`max_tokens` 是必需的上游字段，未覆盖时影策发送 4096。
|
||||
|
||||
## 请求示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/messages" \
|
||||
-H "x-api-key: <API_KEY>" \
|
||||
-H "anthropic-version: 2023-06-01" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "YOUR_CLAUDE_MODEL",
|
||||
"max_tokens": 1200,
|
||||
"system": "你是影视剧本顾问。",
|
||||
"messages": [{"role":"user","content":"指出这一场戏的冲突升级点。"}]
|
||||
}'
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id":"msg_xxx",
|
||||
"type":"message",
|
||||
"role":"assistant",
|
||||
"content":[{"type":"text","text":"冲突分为三个阶段……"}],
|
||||
"stop_reason":"end_turn",
|
||||
"usage":{"input_tokens":31,"output_tokens":148}
|
||||
}
|
||||
```
|
||||
|
||||
## 多内容块、工具与流式
|
||||
|
||||
响应解析遍历 `content[]`，只拼接 `type: text` 的块。`tool_use`、thinking、引用等非文本块不会被误当成正文，但当前统一文本结果也不会保存这些块；需要工具循环或完整块语义时应走专用 Agent 执行层。`stream: true` 的事件流由文本任务链路处理，同步解析器只接收完整 JSON。
|
||||
|
||||
常见错误包括缺少版本头、模型 ID 无权限、交替角色结构不合法、`max_tokens` 缺失或上下文超限。兼容网关可能接受 Bearer 但不接受 `x-api-key`，需要在渠道层确认，不在插件里双发密钥。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [Anthropic Messages API](https://platform.claude.com/docs/en/api/messages)
|
||||
- [Anthropic Messages examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages)
|
||||
|
||||
{{CONTRACT}}
|
||||
61
backend/internal/protocol/docs/gemini-image.md
Normal file
61
backend/internal/protocol/docs/gemini-image.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# Gemini 图片生成
|
||||
|
||||
Gemini 图片插件调用 `generateContent`，把提示词和参考图组织为一个 `user` content。Data URL 被拆为 `inline_data`，外部 URL 被发送为 `file_data.file_uri`；响应从候选内容中的内联图片解析。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1beta/models/{model}:generateContent
|
||||
x-goog-api-key: <GEMINI_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
通过后端渠道中转时，API Key 必须留在服务端头部，不能放进浏览器 URL。Vertex AI 使用不同 Base URL、OAuth 与资源路径，除非网关转换协议，否则不能直接复用此插件。
|
||||
|
||||
## 模型与输出模式
|
||||
|
||||
只有支持原生图片输出的 Gemini 模型才能返回内联图片。模型 ID 原样放进 URL 并进行路径转义。插件不维护模型白名单、图片尺寸表或计费，因为这些应由官方模型页和渠道模型配置共同确定。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
`aspectRatio -> generationConfig.imageConfig.aspectRatio`，`quality -> generationConfig.imageConfig.imageSize`。`extra` 可替换 `generationConfig`、`safetySettings` 和 `systemInstruction`；替换完整配置时调用方必须保留所需图片输出配置。
|
||||
|
||||
## 文生图请求
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1beta/models/YOUR_MODEL:generateContent" \
|
||||
-H "x-goog-api-key: <GEMINI_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"contents":[{"role":"user","parts":[{"text":"复古科幻电影海报，中文标题清晰"}]}],
|
||||
"generationConfig":{"imageConfig":{"aspectRatio":"3:4","imageSize":"2K"}}
|
||||
}'
|
||||
```
|
||||
|
||||
## 参考图请求
|
||||
|
||||
```json
|
||||
{
|
||||
"contents":[{"role":"user","parts":[
|
||||
{"text":"保持人物一致，改为冬季服装"},
|
||||
{"inline_data":{"mime_type":"image/png","data":"<BASE64>"}}
|
||||
]}]
|
||||
}
|
||||
```
|
||||
|
||||
外部 URL 会被构造成 `file_data.file_uri`。该 URI 是否允许任意 HTTP URL 取决于上游；如果官方只接受 Files API URI，必须先上传文件，当前插件不会自动代传。
|
||||
|
||||
## 响应解析与安全
|
||||
|
||||
解析器遍历 `candidates[].content.parts[]`，识别 `inlineData` 或 `inline_data`，再生成 `data:<mime>;base64,...`。只有文本、finishReason 或安全反馈而没有内联图片时请求会失败。大图片不能进入 localStorage，应立即转存到影策资源存储。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [Gemini native image generation](https://ai.google.dev/gemini-api/docs/image-generation)
|
||||
- [Gemini generateContent API](https://ai.google.dev/api/generate-content)
|
||||
|
||||
{{CONTRACT}}
|
||||
72
backend/internal/protocol/docs/gemini-veo.md
Normal file
72
backend/internal/protocol/docs/gemini-veo.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# Gemini Veo 长任务
|
||||
|
||||
Veo 插件通过 `predictLongRunning` 创建 Google long-running operation，再查询 operation 直到完成。提示词位于 `instances[0]`，当前最多取第一张参考图并以内联 Base64 发送。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1beta/models/{model}:predictLongRunning
|
||||
GET {channel_base_url}/v1beta/{operation_name}
|
||||
x-goog-api-key: <GEMINI_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
API Key 必须通过后端头部中转，不能放入浏览器 URL。Vertex AI Veo 的 OAuth、项目、区域和发布者路径不同，不能直接套用 Gemini Developer API Base URL。
|
||||
|
||||
## 模型与能力限制
|
||||
|
||||
模型 ID 原样放入创建路径。允许时长、比例、分辨率、音频、参考图类型、并发、结果保留期和计费以 Google 官方模型页及账户区域为准。插件不维护白名单。当前 adapter 只使用第一张图片；视频/音频参考和水印不发送。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
实际映射为 `aspectRatio`、`durationSeconds`、`resolution`、`generateAudio`，均放入 `parameters`。参考图固定为 `instances[0].image.inlineData`；没有 data URL 时 MIME 和数据会退化为空/通用值，因此远程 URL 应先下载并转为 data URL。
|
||||
|
||||
## 创建任务示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1beta/models/YOUR_VEO_MODEL:predictLongRunning" \
|
||||
-H "x-goog-api-key: <GEMINI_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"instances":[{
|
||||
"prompt":"夜间列车驶过雪原，航拍镜头缓慢下降",
|
||||
"image":{"inlineData":{"mimeType":"image/png","data":"<BASE64>"}}
|
||||
}],
|
||||
"parameters":{"aspectRatio":"16:9","durationSeconds":8,"resolution":"720p","generateAudio":true}
|
||||
}'
|
||||
```
|
||||
|
||||
## Operation 轮询与结果
|
||||
|
||||
创建响应返回 operation `name`。影策会移除开头斜杠，并在缺少 `operations/` 前缀时自动补齐，然后请求 `/v1beta/operations/...`。
|
||||
|
||||
```json
|
||||
{"name":"operations/op_xxx","done":false}
|
||||
```
|
||||
|
||||
该插件使用独立的 Google LRO parser，不经过通用 `status/state` 兼容分支：`done:false` 视为处理中，顶层 `error` 视为失败，`done:true` 后从 `response.generatedVideos[]` 或 `response.generateVideoResponse.generatedSamples[]` 的 `video.uri` 读取视频。成功但缺少视频地址会作为真实错误返回，不把 operation 完成误报为媒体已保存。
|
||||
|
||||
```json
|
||||
{
|
||||
"name":"operations/op_xxx",
|
||||
"done":true,
|
||||
"response":{
|
||||
"generateVideoResponse":{
|
||||
"generatedSamples":[
|
||||
{"video":{"uri":"https://generativelanguage.googleapis.com/v1beta/files/..."}}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [Gemini API video generation with Veo](https://ai.google.dev/gemini-api/docs/video)
|
||||
- [Google long-running operations](https://ai.google.dev/api/files#method:-operations.get)
|
||||
|
||||
{{CONTRACT}}
|
||||
60
backend/internal/protocol/docs/grok-image.md
Normal file
60
backend/internal/protocol/docs/grok-image.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# xAI Grok Images
|
||||
|
||||
Grok Images 插件使用 OpenAI 风格的图片生成路径，但请求字段按 xAI 图片协议构造：`aspect_ratio`、`resolution`，并在有参考图时发送单个 `image`。它不是 OpenAI Images 插件的别名。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/images/generations
|
||||
Authorization: Bearer <XAI_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与支持边界
|
||||
|
||||
模型名由 xAI 账户当前可用模型决定。插件不写死模型、价格、并发或内容限制。当前实现只发送第一张参考图；多参考图、编辑专用路径、mask 和批量生成没有实现，不能因上游可能支持就展示为已支持。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
实际构造为：`aspectRatio -> aspect_ratio`，为空时默认 `1:1`；`quality -> resolution`，为空时默认 `2k`；`images[0] -> image`。`imageCount`、`resolution` 平台字段及其他图片不会发送。
|
||||
|
||||
## 文生图请求
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/images/generations" \
|
||||
-H "Authorization: Bearer <XAI_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_GROK_IMAGE_MODEL",
|
||||
"prompt":"太空港的清晨，宽银幕概念设计",
|
||||
"aspect_ratio":"16:9",
|
||||
"resolution":"2k"
|
||||
}'
|
||||
```
|
||||
|
||||
## 单图参考请求
|
||||
|
||||
```json
|
||||
{
|
||||
"model":"YOUR_GROK_IMAGE_MODEL",
|
||||
"prompt":"保持主体轮廓，改成铅笔分镜风格",
|
||||
"aspect_ratio":"16:9",
|
||||
"resolution":"2k",
|
||||
"image":"https://example.com/reference.png"
|
||||
}
|
||||
```
|
||||
|
||||
## 响应与错误
|
||||
|
||||
插件按 OpenAI Images 风格解析 `data[]` 中的 `url`、`b64_json` 或 `data`。如果 xAI 的实际响应结构发生变化或只返回异步任务，当前解析会失败而不是伪造结果。素材不可达、比例/分辨率不受模型支持、模型无权限和审核拒绝应原样暴露。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [xAI Image Generation](https://docs.x.ai/docs/guides/image-generation)
|
||||
- [xAI API Reference](https://docs.x.ai/docs/api-reference)
|
||||
|
||||
{{CONTRACT}}
|
||||
59
backend/internal/protocol/docs/minimax-video.md
Normal file
59
backend/internal/protocol/docs/minimax-video.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# MiniMax 视频生成
|
||||
|
||||
MiniMax 视频插件使用 `/v2/video_generation` 创建异步任务。它同时发送顶层 `prompt` 和结构化 `content[]`：文本为 text item，参考图片为带 `reference_image` role 的 image URL item。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v2/video_generation
|
||||
GET {channel_base_url}/v2/query/video_generation/{task_id}
|
||||
Authorization: Bearer <MINIMAX_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与约束
|
||||
|
||||
当前 MiniMax V2 官方文档列出 `MiniMax-H3`，时长为 4–15 秒整数，分辨率为 `768P` 或 `2K`，比例支持 `adaptive`、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`。当前 adapter 默认 6 秒；模型名和其他限制仍以账户实际开放能力为准。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
每张图片构造为 `content` 中的 `image_url` item。`extra` 可覆盖 `model`、`prompt`、`duration`、`content`、`resolution`、`aspect_ratio`。参考视频、参考音频、音频生成和水印当前不发送。
|
||||
|
||||
## 创建任务示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v2/video_generation" \
|
||||
-H "Authorization: Bearer <MINIMAX_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_MINIMAX_VIDEO_MODEL",
|
||||
"prompt":"保持角色一致，人物转身看向镜头",
|
||||
"duration":6,
|
||||
"content":[
|
||||
{"type":"text","text":"保持角色一致，人物转身看向镜头"},
|
||||
{"type":"image_url","image_url":{"url":"https://example.com/character.png"},"role":"reference_image"}
|
||||
],
|
||||
"resolution":"720P",
|
||||
"aspect_ratio":"16:9"
|
||||
}'
|
||||
```
|
||||
|
||||
## 查询、文件与结果
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v2/query/video_generation/task_xxx" \
|
||||
-H "Authorization: Bearer <MINIMAX_API_KEY>"
|
||||
```
|
||||
|
||||
当前 V2 官方成功响应在 `task.content.url` 返回视频地址，通用 parser 会先合并 `task`，再从 `content.url` 提取结果。官方仅允许查询最近 7 天任务，视频 URL 有时效，应立即转存。当前 adapter 尚未发送参考视频、参考音频、`callback_url` 或 `aigc_watermark`；虽然 V2 上游支持这些字段，影策不能宣称已支持。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [MiniMax 创建视频生成任务](https://platform.minimaxi.com/docs/api-reference/video-generation-v2-create)
|
||||
- [MiniMax 查询任务](https://platform.minimaxi.com/docs/api-reference/video-generation-v2-query)
|
||||
|
||||
{{CONTRACT}}
|
||||
57
backend/internal/protocol/docs/newapi-channel-1.md
Normal file
57
backend/internal/protocol/docs/newapi-channel-1.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# NewAPI 媒体任务协议
|
||||
|
||||
该插件把多模态参考素材统一包装为 `input.media[]`，把分辨率、比例、时长和水印放入 `parameters`，使用 `/v1/videos` 创建与查询异步任务。它是影策适配的渠道合同，不是某一家模型厂商的官方协议。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/videos
|
||||
GET {channel_base_url}/v1/videos/{task_id}
|
||||
Authorization: Bearer <CHANNEL_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型、计费与素材上限
|
||||
|
||||
模型清单、计费、时长范围、素材数量和单文件大小均由当前 NewAPI 部署及其上游渠道决定。此插件不能把某个渠道的 Seedance、Veo 或 Kling 限制推广给所有部署。管理员应在模型配置中记录经过实际调用验证的模型 ID。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
实际映射：图片 -> `{type:"reference_image"}`，视频 -> `{type:"reference_video"}`，音频 -> `{type:"reference_voice"}`；均放入 `input.media`。默认 `resolution=720P`、`ratio=16:9`、`duration=5`。只有 `watermark=true` 时才发送水印字段；`generateAudio` 当前不发送。
|
||||
|
||||
## 多模态创建示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/videos" \
|
||||
-H "Authorization: Bearer <CHANNEL_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_CHANNEL_MODEL",
|
||||
"input":{
|
||||
"prompt":"保持人物外观，动作参考视频，节奏参考声音",
|
||||
"media":[
|
||||
{"type":"reference_image","url":"https://example.com/character.png"},
|
||||
{"type":"reference_video","url":"https://example.com/action.mp4"},
|
||||
{"type":"reference_voice","url":"https://example.com/beat.mp3"}
|
||||
]
|
||||
},
|
||||
"parameters":{"resolution":"720P","ratio":"16:9","duration":8,"watermark":false}
|
||||
}'
|
||||
```
|
||||
|
||||
## 响应、轮询与排错
|
||||
|
||||
创建响应必须在顶层、`task` 或 `data` 中包含 `id/task_id/taskId/request_id`。查询使用 URL 编码后的任务 ID。完成时解析视频数组或 `video_url/videoUrl/result_url/url`。如果渠道返回自己的深层字段，必须新增专属解析，不能把空结果标记成功。
|
||||
|
||||
常见问题包括渠道未映射模型、素材 URL 无法由上游下载、媒体类型命名不被该部署接受、默认参数超出模型范围。先检查部署版本和渠道日志，再修改适配器；不要反复添加兼容别名掩盖协议差异。
|
||||
|
||||
## 官方资料与边界
|
||||
|
||||
- NewAPI 项目与部署文档由具体运维方提供；本页以影策当前 adapter 的请求事实为准。
|
||||
- 上游模型官方文档只用于确认模型自身能力，不能替代 NewAPI 网关字段合同。
|
||||
|
||||
{{CONTRACT}}
|
||||
63
backend/internal/protocol/docs/newapi-channel-2.md
Normal file
63
backend/internal/protocol/docs/newapi-channel-2.md
Normal file
@@ -0,0 +1,63 @@
|
||||
# NewAPI Video Generations
|
||||
|
||||
该插件使用 `/v1/video/generations` JSON 异步接口，直接发送图片、视频和音频 URL 数组。它适用于实现这一特定路径和字段集合的 NewAPI 渠道，不等同于 `/v1/videos` 媒体任务协议。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/video/generations
|
||||
GET {channel_base_url}/v1/video/generations/{task_id}
|
||||
Authorization: Bearer <CHANNEL_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与约束来源
|
||||
|
||||
可用模型、每种素材上限、时长范围、音频能力、分辨率和计费由该 NewAPI 部署映射的上游决定。插件没有通用白名单。用户示例中的 Seedance 限制只可用于实际连接该服务且管理员验证一致的渠道。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
实际字段为 `model`、`prompt`、`seconds`、`aspect_ratio`、可选 `resolution`、`generate_audio`、`image_urls`、`video_urls`、`audio_urls`。时长默认 6 秒并发送为字符串，比例默认 `16:9`。水印当前不发送。
|
||||
|
||||
## 完整多模态请求
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/video/generations" \
|
||||
-H "Authorization: Bearer <CHANNEL_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_VIDEO_MODEL",
|
||||
"prompt":"人物参考第一张图，镜头运动参考视频，节奏跟随音频",
|
||||
"seconds":"10",
|
||||
"aspect_ratio":"9:16",
|
||||
"resolution":"720p",
|
||||
"generate_audio":true,
|
||||
"image_urls":["https://example.com/subject.png"],
|
||||
"video_urls":["https://example.com/motion.mp4"],
|
||||
"audio_urls":["https://example.com/beat.mp3"]
|
||||
}'
|
||||
```
|
||||
|
||||
## 任务状态与结果
|
||||
|
||||
```json
|
||||
{"task_id":"task_xxx","status":"queued"}
|
||||
```
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/video/generations/task_xxx" \
|
||||
-H "Authorization: Bearer <CHANNEL_API_KEY>"
|
||||
```
|
||||
|
||||
状态会归一为等待、处理中、成功或失败。成功结果可来自视频数组或常见顶层 URL；当前没有取消路径。任务失败后的退款、额度释放和结果保留期属于部署方账务合同，影策不会在没有接口证据时承诺。
|
||||
|
||||
## 官方资料与边界
|
||||
|
||||
- 以连接的 NewAPI 部署接口文档、版本和渠道配置为准。
|
||||
- 素材必须能被网关和最终上游访问；网关可访问不代表最终供应商可访问。
|
||||
|
||||
{{CONTRACT}}
|
||||
66
backend/internal/protocol/docs/newapi.md
Normal file
66
backend/internal/protocol/docs/newapi.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# OpenAI Videos 兼容协议
|
||||
|
||||
该插件实现 `/v1/videos` 异步视频合同：以 multipart 创建任务，取得任务 ID 后查询同一路径下的任务资源。它用于 Sora/OpenAI Videos 风格渠道；模型、尺寸、时长、价格和保留期由实际渠道决定。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/videos
|
||||
GET {channel_base_url}/v1/videos/{task_id}
|
||||
Authorization: Bearer <API_KEY>
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
## 模型与能力边界
|
||||
|
||||
模型名必须是部署服务实际开放的视频模型。插件不把任意 `sora-*` 或 `sd-*` 名称视为可用，也不提供价格表。当前实现支持文生视频和单组参考图输入，不发送参考视频、参考音频、独立音频开关或水印。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
`duration -> seconds`，发送为十进制字符串；`aspectRatio -> size`，这里应填写上游尺寸而不是只写 `16:9`；`images -> input_reference` multipart 部件。空字段不发送。
|
||||
|
||||
## 文生视频示例
|
||||
|
||||
```bash
|
||||
curl -X POST "{channel_base_url}/v1/videos" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-F "model=YOUR_VIDEO_MODEL" \
|
||||
-F "prompt=清晨薄雾中的竹林，镜头缓慢向前推进" \
|
||||
-F "seconds=8" \
|
||||
-F "size=1280x720"
|
||||
```
|
||||
|
||||
## 图片参考示例
|
||||
|
||||
```bash
|
||||
curl -X POST "{channel_base_url}/v1/videos" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-F "model=YOUR_VIDEO_MODEL" \
|
||||
-F "prompt=保持参考图人物一致，镜头从中景推进到特写" \
|
||||
-F "seconds=8" \
|
||||
-F "size=720x1280" \
|
||||
-F "input_reference=@character.png"
|
||||
```
|
||||
|
||||
## 创建、轮询与下载
|
||||
|
||||
```json
|
||||
{"id":"task_xxx","status":"queued"}
|
||||
```
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/videos/task_xxx" -H "Authorization: Bearer <API_KEY>"
|
||||
```
|
||||
|
||||
完成响应可在顶层或嵌套对象提供 `url`、`video_url`、`result_url` 或视频数组。失败消息从 `message`、`error`、`fail_reason` 提取。当前插件没有取消接口，也不会自动删除上游任务；轮询间隔和下载有效期必须服从渠道说明。
|
||||
|
||||
## 官方与兼容资料
|
||||
|
||||
- [OpenAI Videos API reference](https://developers.openai.com/api/reference/resources/videos)
|
||||
- 若渠道是 NewAPI 或其他兼容实现，还必须核对该部署的版本说明；路径相同不等于字段和模型完全一致。
|
||||
|
||||
{{CONTRACT}}
|
||||
57
backend/internal/protocol/docs/novita-video.md
Normal file
57
backend/internal/protocol/docs/novita-video.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# Novita 视频异步 API
|
||||
|
||||
Novita 视频插件使用 `/v3/video/create` 创建任务，以 query 参数携带任务 ID 查询统一异步结果。模型字段名为 `model_name`，不是通用 `model`。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v3/video/create
|
||||
GET {channel_base_url}/v3/async/task-result?task_id={id}
|
||||
Authorization: Bearer <NOVITA_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与约束
|
||||
|
||||
Novita 聚合多个视频模型，不同 `model_name` 的字段、图片要求、时长、比例和价格可能不同。当前插件只提供共同子集：提示词、单张参考图、时长和比例；不能据此认定所有 Novita 视频模型都接受相同参数。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
`model -> model_name`，`images[0] -> image_url`，时长默认 5 秒，比例默认 `16:9`。`resolution`、参考视频、参考音频、音频生成和水印当前不发送。
|
||||
|
||||
## 创建请求示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v3/video/create" \
|
||||
-H "Authorization: Bearer <NOVITA_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model_name":"YOUR_NOVITA_VIDEO_MODEL",
|
||||
"prompt":"产品在黑色展台上缓慢旋转，轮廓光",
|
||||
"duration":5,
|
||||
"aspect_ratio":"16:9",
|
||||
"image_url":"https://example.com/product.png"
|
||||
}'
|
||||
```
|
||||
|
||||
## 查询与下载
|
||||
|
||||
创建响应应返回 `task_id/id`。查询时任务 ID会进行 URL query 编码：
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v3/async/task-result?task_id=task_xxx" \
|
||||
-H "Authorization: Bearer <NOVITA_API_KEY>"
|
||||
```
|
||||
|
||||
成功结果由统一 parser 从视频数组或 URL 字段读取。Novita 若针对某模型返回独特嵌套结构，应建立该模型 fixture，而不是继续扩展全局模糊字段。当前没有取消接口；任务退款和结果保留期以 Novita 当前规则为准。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [Novita Unified Video Generation](https://novita.ai/docs/api-reference/reference-unified-video-generation)
|
||||
- [Novita Task Result Query](https://novita.ai/docs/api-reference/model-apis-task-result)
|
||||
|
||||
{{CONTRACT}}
|
||||
50
backend/internal/protocol/docs/openai-audio.md
Normal file
50
backend/internal/protocol/docs/openai-audio.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# OpenAI Audio Speech
|
||||
|
||||
该插件调用 OpenAI 风格的同步文字转语音接口，把影策提示词映射为 `input`。当前只发送模型与文本，声音、格式、语速和其他 TTS 选项尚未纳入 adapter。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/audio/speech
|
||||
Authorization: Bearer <API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型、声音与输出格式
|
||||
|
||||
模型、voice、格式、单次文本长度、流式能力和价格以 OpenAI 或兼容渠道实际文档为准。当前影策 metadata 没有声明参数表，这意味着只有 `model` 和 `prompt` 的内部映射稳定，不意味着上游没有必填 `voice`。若上游要求 voice，管理员必须先扩展 adapter，不能依赖未白名单的字段自动透传。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
实际请求正文固定为：
|
||||
|
||||
```json
|
||||
{"model":"YOUR_TTS_MODEL","input":"请在午夜前离开这座城市。"}
|
||||
```
|
||||
|
||||
完整上游常见请求参考：
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/audio/speech" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"model":"YOUR_TTS_MODEL","voice":"YOUR_VOICE","input":"请在午夜前离开这座城市。","response_format":"mp3"}' \
|
||||
--output speech.mp3
|
||||
```
|
||||
|
||||
第二个示例包含当前 adapter 尚未发送的 `voice` 和 `response_format`，用于说明必须补齐的协议字段。
|
||||
|
||||
## 响应与当前实现差异
|
||||
|
||||
OpenAI 官方 Speech API 通常直接返回音频二进制流；当前 `parseAudioResponse` 却按 JSON 中的 `url/audio_url/data` 解析。因此本插件当前更适合“返回音频 URL JSON”的兼容渠道，不能宣称已经正确处理 OpenAI 官方二进制响应。直连官方服务前必须增加二进制响应合同、MIME/文件名处理和资源保存测试。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [OpenAI Text-to-speech guide](https://developers.openai.com/api/docs/guides/text-to-speech)
|
||||
- [OpenAI Audio Speech reference](https://developers.openai.com/api/reference/resources/audio/subresources/speech/methods/create)
|
||||
|
||||
{{CONTRACT}}
|
||||
73
backend/internal/protocol/docs/openai-image.md
Normal file
73
backend/internal/protocol/docs/openai-image.md
Normal file
@@ -0,0 +1,73 @@
|
||||
# OpenAI Images
|
||||
|
||||
OpenAI Images 插件实现 JSON 文生图请求，并解析 OpenAI Images 风格的 `data[]` 响应。上游官方还提供 multipart 图像编辑接口，但当前影策适配器的创建路径只构造 `/v1/images/generations`；详情中列出编辑接口是为了说明协议能力，不代表当前画布已发送编辑请求。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/images/generations
|
||||
Authorization: Bearer <API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
官方编辑接口为 `POST /v1/images/edits`、`multipart/form-data`。当前适配器未在有参考图时切换到该路径，这是明确的实现缺口。
|
||||
|
||||
## 模型、尺寸与质量
|
||||
|
||||
模型、允许尺寸、质量枚举、单次张数和计费会随上游服务变化，插件不维护可能过期的白名单。渠道若是 OpenAI 兼容实现，必须分别验证它是否支持 `n`、`quality`、`background`、`output_format` 和 Base64 响应。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
当前实现：`imageCount -> n`、`aspectRatio -> size`、`quality -> quality`；`extra` 可透传 `size`、`quality`、`background`、`response_format`、`output_format`、`style`、`n`。`images` 和 `resolution` 当前不会进入文生图请求。
|
||||
|
||||
## 文生图请求
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/images/generations" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_IMAGE_MODEL",
|
||||
"prompt":"雨夜便利店门口，青绿色霓虹，电影剧照",
|
||||
"size":"1536x1024",
|
||||
"quality":"high",
|
||||
"n":1
|
||||
}'
|
||||
```
|
||||
|
||||
URL 响应：
|
||||
|
||||
```json
|
||||
{"created":1780000000,"data":[{"url":"https://cdn.example/generated.png"}]}
|
||||
```
|
||||
|
||||
Base64 响应：
|
||||
|
||||
```json
|
||||
{"created":1780000000,"data":[{"b64_json":"iVBORw0KGgo..."}]}
|
||||
```
|
||||
|
||||
解析器遍历 `data[]`，优先识别 `url`，也接受 `b64_json` 或 `data`。URL 应立即下载；裸 Base64 会转为 `data:image/png;base64,...`，已带 data URL 前缀的值保持不变。若渠道使用 WebP/JPEG Base64 且响应不返回 MIME，当前协议无法可靠推断格式，应优先请求 URL 或补充带 MIME 的响应合同。
|
||||
|
||||
## 图像编辑参考请求
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/images/edits" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-F "model=YOUR_IMAGE_MODEL" \
|
||||
-F "image=@reference.png" \
|
||||
-F "prompt=保持人物一致，改成雨夜街道"
|
||||
```
|
||||
|
||||
该示例是上游协议参考；在影策中使用前必须补 multipart 构造、参考图数量与 MIME 校验、编辑响应测试。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [OpenAI Image generation guide](https://developers.openai.com/api/docs/guides/image-generation)
|
||||
- [OpenAI Images API reference](https://developers.openai.com/api/reference/resources/images)
|
||||
|
||||
{{CONTRACT}}
|
||||
71
backend/internal/protocol/docs/openai-response.md
Normal file
71
backend/internal/protocol/docs/openai-response.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# OpenAI Responses API
|
||||
|
||||
Responses API 是 OpenAI 当前统一的文本与工具调用接口，输入使用 `input`，可同时承载简单字符串、结构化消息和工具回合。影策默认发送字符串提示词，并从同步响应的 `output_text` 或 `output[]` 中提取文本。
|
||||
|
||||
## 接口、鉴权与请求模式
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/responses
|
||||
Authorization: Bearer <API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与能力发现
|
||||
|
||||
插件不硬编码模型表。请使用渠道模型管理中已验证支持 Responses API 的模型 ID。兼容服务即使实现 `/v1/responses`，也可能不支持内置工具、状态延续、结构化输出或多模态输入，能力必须以该服务文档和实际探测为准。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
`extra` 可透传 `input`、`instructions`、`temperature`、`top_p`、`max_output_tokens`、`stream`、`tools` 和 `text`。`extra.input` 会替换默认字符串；复杂输入必须使用上游规定的 item 结构，不应把 Chat Completions 的 `messages` 原样塞进来。
|
||||
|
||||
## 请求示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/responses" \
|
||||
-H "Authorization: Bearer <API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "YOUR_MODEL",
|
||||
"instructions": "输出可直接拍摄的镜头清单。",
|
||||
"input": "一名女孩在停电的商场里寻找出口。",
|
||||
"max_output_tokens": 1200
|
||||
}'
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "resp_xxx",
|
||||
"status": "completed",
|
||||
"output_text": "镜头 1……",
|
||||
"usage": {"input_tokens":28,"output_tokens":174,"total_tokens":202}
|
||||
}
|
||||
```
|
||||
|
||||
## 结构化输入示例
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "YOUR_MODEL",
|
||||
"input": [{
|
||||
"role": "user",
|
||||
"content": [{"type":"input_text","text":"分析这段剧情的节奏问题"}]
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
## 响应解析与限制
|
||||
|
||||
解析器优先读取顶层 `output_text`；缺失时遍历 `output`，尝试读取 item 的 `text` 或 `content`，并保留 `usage`。当前实现没有完整执行 function call、computer use、file search 等输出 item，也不通过 `previous_response_id` 自动续接状态。需要这些能力时必须在 Agent 调用链中显式实现，不能只靠文档声称支持。
|
||||
|
||||
流式响应由文本事件链路处理。上游拒绝、模型不支持、输入结构错误、输出 token 超限和工具参数校验失败均应作为失败返回。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [OpenAI Responses API Reference](https://developers.openai.com/api/reference/resources/responses/methods/create)
|
||||
- [OpenAI Responses migration guide](https://developers.openai.com/api/docs/guides/migrate-to-responses)
|
||||
|
||||
{{CONTRACT}}
|
||||
61
backend/internal/protocol/docs/volcengine-ark-image.md
Normal file
61
backend/internal/protocol/docs/volcengine-ark-image.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# 火山方舟图片生成
|
||||
|
||||
本插件面向火山方舟 Ark 图片生成 JSON 接口。提示词直接发送，参考图数组映射到 `image`，连续生成和水印参数可从模型扩展字段透传。
|
||||
|
||||
## 接口、鉴权与区域
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/api/v3/images/generations
|
||||
Authorization: Bearer <ARK_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Base URL、鉴权方式和可用模型受火山方舟控制台、区域与接入方式影响。若使用 AK/SK 签名网关，应由渠道层完成签名，不能把 Secret Key 写入插件文档或浏览器。
|
||||
|
||||
## 模型与支持边界
|
||||
|
||||
模型 ID、尺寸范围与能力以火山方舟控制台为准。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
当前实现：`aspectRatio -> size`，所有 `images -> image[]`；`extra` 可透传 `size`、`sequential_image_generation`、`sequential_image_generation_options`、`watermark`。`imageCount`、`quality` 与 `resolution` 没有通用映射，必须按模型接口另行适配。
|
||||
|
||||
## 文生图示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/api/v3/images/generations" \
|
||||
-H "Authorization: Bearer <ARK_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_ARK_ENDPOINT_OR_MODEL",
|
||||
"prompt":"古城屋顶追逐，低机位，动态构图",
|
||||
"size":"2048x1152",
|
||||
"watermark":false
|
||||
}'
|
||||
```
|
||||
|
||||
## 参考图示例
|
||||
|
||||
```json
|
||||
{
|
||||
"model":"YOUR_ARK_ENDPOINT_OR_MODEL",
|
||||
"prompt":"保持人物服装和发型，生成侧面中景",
|
||||
"image":["https://example.com/character.png"],
|
||||
"size":"2048x1152"
|
||||
}
|
||||
```
|
||||
|
||||
## 响应解析与限制
|
||||
|
||||
响应按 `data[]` 图片数组解析，元素需包含 `url`、`b64_json` 或 `data`。当前插件没有为 Ark 特有错误码、任务模式或内容过滤结果做专属解包；渠道返回非兼容结构时会明确失败。模型尺寸、参考图数量、序列图上限、水印和计费以控制台当前模型说明为准，不能从插件默认值推断。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [火山方舟视觉模型 API 文档](https://www.volcengine.com/docs/82379)
|
||||
- [火山方舟 API 接入与鉴权文档](https://www.volcengine.com/docs/82379/1263279)
|
||||
|
||||
{{CONTRACT}}
|
||||
57
backend/internal/protocol/docs/volcengine-ark-video.md
Normal file
57
backend/internal/protocol/docs/volcengine-ark-video.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# 火山方舟视频任务
|
||||
|
||||
本插件使用 Ark Contents Generations Tasks 异步接口。提示词和参考图组成 `content[]`；比例、分辨率、时长、音频和水印位于顶层任务参数。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/api/v3/contents/generations/tasks
|
||||
GET {channel_base_url}/api/v3/contents/generations/tasks/{task_id}
|
||||
Authorization: Bearer <ARK_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与约束
|
||||
|
||||
模型通常对应控制台可用模型或 endpoint ID。允许时长、分辨率、画幅、参考图数量、是否可生成音频及计费由具体模型决定。插件默认 5 秒、`16:9`、`720p`，默认值不是上游能力承诺。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
每张图片构造为 `{"type":"image_url","image_url":{"url":"..."},"role":"reference_image"}`。当前不发送参考视频与参考音频；`generate_audio` 和 `watermark` 只在 true 时发送。
|
||||
|
||||
## 创建任务示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/api/v3/contents/generations/tasks" \
|
||||
-H "Authorization: Bearer <ARK_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_ARK_VIDEO_MODEL",
|
||||
"content":[
|
||||
{"type":"text","text":"保持人物一致，镜头缓慢环绕"},
|
||||
{"type":"image_url","image_url":{"url":"https://example.com/subject.png"},"role":"reference_image"}
|
||||
],
|
||||
"ratio":"16:9",
|
||||
"resolution":"720p",
|
||||
"duration":5,
|
||||
"generate_audio":true,
|
||||
"watermark":false
|
||||
}'
|
||||
```
|
||||
|
||||
## 查询、状态与结果
|
||||
|
||||
创建响应任务 ID 由统一解析器从顶层、`task` 或 `data` 提取。查询成功后读取视频数组或常见 URL 字段。若 Ark 把结果放在其他嵌套路径，必须用真实 fixture 增加专属解析，不允许只根据 `completed` 返回空成功。
|
||||
|
||||
任务失败可能来自 endpoint 不可用、素材下载失败、参数组合不受支持、内容审核、并发或额度限制。上游 request ID 应保留用于排查，API Key 和素材正文不得进入日志。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [火山方舟视频生成 API](https://www.volcengine.com/docs/82379)
|
||||
- [火山方舟内容生成任务文档](https://www.volcengine.com/docs/82379/1520757)
|
||||
|
||||
{{CONTRACT}}
|
||||
57
backend/internal/protocol/docs/volcengine-jimeng-image.md
Normal file
57
backend/internal/protocol/docs/volcengine-jimeng-image.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# 即梦官方图片异步 API
|
||||
|
||||
本插件使用即梦视觉异步任务模式：提交任务取得 `task_id`，再以相同 `req_key` 查询结果。接口由火山引擎视觉服务的 AK/SK 签名体系保护，不是 Bearer 兼容接口。
|
||||
|
||||
## 接口与签名
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
逻辑操作名为 `CVSync2AsyncSubmitTask` 和 `CVSync2AsyncGetResult`。实际主机、Query 参数、Service/Region 与签名头由渠道的火山签名实现负责；不能只对这两个字符串执行普通 HTTP POST。
|
||||
|
||||
## 模型与 req_key
|
||||
|
||||
影策模型 ID 映射为 `req_key`，必须与已开通的即梦能力完全一致。插件不提供可能过期的 `req_key` 白名单，也不根据名字推断文生图、图生图或版本能力。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
当前实现发送 `req_key`、`prompt`，有参考图时发送 `image_urls`。`extra` 可覆盖 `req_key`、`prompt`、`image_urls`、`seed`、`width`、`height`。平台的 `aspectRatio`、`quality`、`resolution` 和 `imageCount` 没有自动转换。
|
||||
|
||||
## 创建请求正文
|
||||
|
||||
```json
|
||||
{
|
||||
"req_key":"YOUR_JIMENG_REQ_KEY",
|
||||
"prompt":"悬疑短剧分镜，楼道尽头的逆光人影",
|
||||
"image_urls":["https://example.com/reference.png"],
|
||||
"width":1536,
|
||||
"height":1024,
|
||||
"seed":42
|
||||
}
|
||||
```
|
||||
|
||||
创建响应至少需要可识别任务 ID：
|
||||
|
||||
```json
|
||||
{"data":{"task_id":"task_xxx"}}
|
||||
```
|
||||
|
||||
## 轮询请求与结果
|
||||
|
||||
```json
|
||||
{"req_key":"YOUR_JIMENG_REQ_KEY","task_id":"task_xxx"}
|
||||
```
|
||||
|
||||
轮询响应从顶层、`task` 或 `data` 读取状态，并按图片类型提取 `images`、`image_url`、`imageUrl`、`result_url` 或 `url`；图片数组可包含 URL 字符串或对象。若结果只出现在即梦其他专属嵌套字段中，需要补 fixture 和专属解析，不能把“拿到 completed”当作已经保存图片。
|
||||
|
||||
## 错误与排查
|
||||
|
||||
签名时间偏差、Region/Service 错误、`req_key` 未开通、素材不可下载、宽高不支持和内容审核都会导致失败。日志可以记录请求 ID 和错误码，不得记录 Secret Key、完整签名或私有素材 data URL。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [火山引擎视觉智能开放平台](https://www.volcengine.com/docs/85621)
|
||||
- [火山引擎签名方法](https://www.volcengine.com/docs/6369/67269)
|
||||
|
||||
{{CONTRACT}}
|
||||
55
backend/internal/protocol/docs/volcengine-jimeng-video.md
Normal file
55
backend/internal/protocol/docs/volcengine-jimeng-video.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# 即梦官方视频异步 API
|
||||
|
||||
即梦视频插件使用 `CVSync2AsyncSubmitTask` 创建、`CVSync2AsyncGetResult` 查询，并由渠道的火山 AK/SK 实现完成签名。创建与查询均为 POST，模型能力键通过 `req_key` 传递。
|
||||
|
||||
## 接口与签名
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
这两个名称是视觉服务 Action，实际 URL、Query、Region、Service、时间戳和签名头必须按火山官方签名规范生成。把 AK/SK 放入 JSON 或浏览器会造成密钥泄漏。
|
||||
|
||||
## 模型、版本与素材限制
|
||||
|
||||
`req_key` 必须是账户已开通的即梦视频能力键。每个版本对首帧/尾帧、参考图数量、时长、比例和分辨率的约束不同；插件不维护一张可能过期的模型表。当前只映射参考图片，不发送参考视频、音频、生成音频或水印。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
基础请求包含 `req_key`、`prompt`、可选 `image_urls`。`extra` 可透传并覆盖 `req_key`、`prompt`、`image_urls`、`duration`、`ratio`、`resolution`，适合管理员按已确认的官方版本补参数。
|
||||
|
||||
## 创建任务正文
|
||||
|
||||
```json
|
||||
{
|
||||
"req_key":"YOUR_JIMENG_VIDEO_REQ_KEY",
|
||||
"prompt":"保持参考人物，镜头从全景移动到近景",
|
||||
"image_urls":["https://example.com/subject.png"],
|
||||
"duration":5,
|
||||
"ratio":"16:9",
|
||||
"resolution":"720p"
|
||||
}
|
||||
```
|
||||
|
||||
创建响应：
|
||||
|
||||
```json
|
||||
{"data":{"task_id":"task_xxx"}}
|
||||
```
|
||||
|
||||
查询正文：
|
||||
|
||||
```json
|
||||
{"req_key":"YOUR_JIMENG_VIDEO_REQ_KEY","task_id":"task_xxx"}
|
||||
```
|
||||
|
||||
## 轮询、结果与失败
|
||||
|
||||
轮询响应由统一异步 parser 读取状态和视频 URL。查询必须继续携带创建时的模型 `req_key`，不能只传任务 ID。签名时间偏差、Region 错误、能力未开通、素材 URL 失效、参数不匹配和审核均会失败。当前没有取消接口，失败后的额度处理以官方账务为准。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [火山引擎视觉智能开放平台](https://www.volcengine.com/docs/85621)
|
||||
- [火山引擎 API 签名方法](https://www.volcengine.com/docs/6369/67269)
|
||||
|
||||
{{CONTRACT}}
|
||||
55
backend/internal/protocol/docs/xai-video.md
Normal file
55
backend/internal/protocol/docs/xai-video.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# xAI 视频生成
|
||||
|
||||
xAI 视频插件创建异步 generation request，再按 request ID 查询。单张参考图发送为 `image`，多张参考图发送为 `reference_images`；时长、画幅和分辨率使用 xAI 风格字段。
|
||||
|
||||
## 接口与鉴权
|
||||
|
||||
{{OPERATIONS}}
|
||||
|
||||
```http
|
||||
POST {channel_base_url}/v1/videos/generations
|
||||
GET {channel_base_url}/v1/videos/{request_id}
|
||||
Authorization: Bearer <XAI_API_KEY>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## 模型与当前支持
|
||||
|
||||
模型 ID、允许时长、比例、分辨率、参考图数量、审核规则和计费以 xAI 控制台及官方文档为准。当前 adapter 默认 6 秒、`16:9`、`720p`。视频参考、音频参考、音频生成开关和水印均不会发送。
|
||||
|
||||
## 参数与字段映射
|
||||
|
||||
{{PARAMETERS}}
|
||||
|
||||
单图结构：`"image":{"url":"..."}`；多图结构：`"reference_images":[{"url":"..."}]`。URL 或 data URL 是否被具体模型接受，应在调用前验证。
|
||||
|
||||
## 请求示例
|
||||
|
||||
```bash
|
||||
curl "{channel_base_url}/v1/videos/generations" \
|
||||
-H "Authorization: Bearer <XAI_API_KEY>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model":"YOUR_XAI_VIDEO_MODEL",
|
||||
"prompt":"雨夜都市追逐，手持摄影，真实运动模糊",
|
||||
"duration":8,
|
||||
"aspect_ratio":"16:9",
|
||||
"resolution":"720p",
|
||||
"image":{"url":"https://example.com/character.png"}
|
||||
}'
|
||||
```
|
||||
|
||||
## 创建、查询与下载
|
||||
|
||||
创建响应需包含 `request_id` 或其他统一解析器支持的任务字段。查询完成后从视频数组或 `video_url/result_url/url` 读取媒体。当前没有 cancel adapter；关闭影策弹窗不会取消上游生成。结果 URL 应及时转存，不能假定永久有效。
|
||||
|
||||
## 错误处理
|
||||
|
||||
模型权限、无效尺寸、参考素材不可访问、内容审核、速率或余额限制必须作为真实失败展示。若官方响应结构与通用解析器不一致，应补 xAI 专属 parser 和 fixture 测试，而不是继续堆叠模糊字段猜测。
|
||||
|
||||
## 官方资料
|
||||
|
||||
- [xAI Video Generation guide](https://docs.x.ai/docs/guides/video-generation)
|
||||
- [xAI API Reference](https://docs.x.ai/docs/api-reference)
|
||||
|
||||
{{CONTRACT}}
|
||||
Reference in New Issue
Block a user