把媒体模型作为 Agent 工具
图片、视频和音频模型不能作为 Agent 的对话模型，因为 Agent 工具需要文本输出、流式响应和工具调用。它们仍可以作为 Agent 调用的工具：保留一个文本模型作为 Agent 的大脑，再把一份能力指令交给 Agent，说明如何调用这个媒体模型。
模型详情页的「Agent 工具」按钮会为媒体模型打开这套配置。
适用场景
- Agent 已经运行在支持工具调用的文本模型上。
- 用户可能要求 Agent 生成图片、视频或语音。
- 你已经拿到模型 ID，以及有权调用该模型的 API Key。
1. 配置 API Key
在设置了 INONEAPI_API_KEY 的终端中启动 Agent。
macOS 或 Linux：
export INONEAPI_API_KEY="ioa_sk_..."需要长期生效时，把 export 写入 ~/.zshrc 或 ~/.bashrc，然后重新打开终端。Windows PowerShell：
[Environment]::SetEnvironmentVariable("INONEAPI_API_KEY", "ioa_sk_...", "User")设置后重新打开 PowerShell。不要把 Key 写进提示词、skill 文件、项目文件或仓库。Agent 支持密钥存储或环境变量注入时，优先使用这些方式。
2. 复制能力指令
在模型详情页打开「Agent 工具」，选择 API Key，然后复制能力指令。指令的说明文字跟随当前页面语言；API 字段名、枚举值和 JSON 保持英文，便于 Agent 与代码工具稳定解析。
指令包含：
- 公共模型 ID 和该模态的端点。
- 完整的公共请求字段，以及每个字段的类型、允许值和是否必填。
- 仅该模型已声明的生成参数及其取值范围。
- 固定的返回值结构和结果保存方式。
- 重试、计费和报错规则。
把指令粘贴到 Agent 的系统提示词、AGENTS.md 或 CLAUDE.md 等项目指令，或 skill / 工具定义中。Agent 仍应使用用户的语言回复。
指令不包含 Key，只从环境变量读取 INONEAPI_API_KEY，因此轮换 Key 时不需要修改指令。
替换提示词
指令请求体中的 <USER_PROMPT> 是占位符，不是要发送的文本。Agent 在发送前必须把整个字符串值替换成用户的实际需求，并保持 JSON 合法：转义双引号和换行。
{"model":"YOUR_MODEL_ID","prompt":"<USER_PROMPT>"}用户要求生成一只白猫时，替换后的请求体是：
{"model":"YOUR_MODEL_ID","prompt":"一只白猫坐在窗台上"}不要把 <USER_PROMPT> 原样发出，也不要在占位符外面再套一层说明文字。
2.1 图片
端点：POST /v1/images/generations。
| 字段 | 类型 | 说明 |
|---|---|---|
model | string | 必填公共模型 ID；平台转发时替换为服务商模型 ID。 |
prompt | string | 必填提示词，描述主体、构图、风格、文字及约束。长度上限由模型决定。 |
n | integer | 可选图片数量，1–6。只有模型详情页标注「输出数量」的模型生效；其他模型传入也只返回一张且不报错。 |
size | string | 可选 WIDTHxHEIGHT 或 auto。是否支持具体尺寸由模型决定，网关不缩放。 |
resolution | string | 可选，size 的别名；两者同时出现时以 size 为准。 |
quality | string | 可选 auto、low、medium、high，或部分旧模型的 standard、hd。不是同一模型全支持。 |
style | string | 可选 vivid 或 natural，仅支持风格参数的模型有效。 |
response_format | string | 可选 url 或 b64_json。GPT Image 系列固定返回 Base64，不支持此字段，应省略。 |
background | string | 可选 auto、opaque、transparent。透明背景需要模型支持，且不能配 jpeg。 |
output_format | string | 可选 png、jpeg、webp，仅在模型支持时传入。 |
output_compression | integer | 可选 0–100，仅 jpeg/webp 有损输出使用。 |
moderation | string | 可选 auto 或 low，仅在模型支持时传入。 |
user | string | 可选业务终端用户标识；不要填邮箱、手机号等敏感信息。 |
stream | boolean | 可选，默认非流式。模型不支持流式时返回 400 PROTOCOL_STREAM_UNSUPPORTED。 |
partial_images | integer | 可选 0–3，仅流式时使用；表示最多部分图像事件数，不是输出图片总数。 |
input_references | array | 可选参考素材，结构见下方。 |
input_references 是 InOneAPI 扩展，每项结构固定：
{"type":"image","role":"reference","source":{"type":"file","file_id":"..."}}type：image、video或audio，必须与实际素材一致。role：first_frame、last_frame、reference或speech，模型不一定支持所有角色。source.type：url、file（兼容别名file_id）或data，一个 source 只指定一种来源。source.url、source.file_id、source.data：与来源类型对应的值。文件必须先通过文件 API 上传，不能使用服务商自己的文件 ID。
固定返回值（JSON）：
| 字段 | 类型 | 说明 |
|---|---|---|
created | integer | Unix 秒级生成时间。 |
data | array | 结果数组，通常每张图片一个对象，但失败时不能假定数量完整。 |
data[].b64_json | string | Base64 原始图像字节，不含 data URL 前缀；与 url 二选一。 |
data[].url | string | 临时下载地址；与 b64_json 二选一，需及时下载。 |
data[].revised_prompt | string | 可选，服务商实际使用的修订提示词。 |
background、output_format、size、quality | string | 可选实际生成元数据，以服务商返回为准。 |
usage | object | 可选 token 计量，含 input_tokens、output_tokens、total_tokens、input_tokens_details.text_tokens、input_tokens_details.image_tokens。缺失 usage 不代表免费。 |
Agent 必须在收到响应后立即保存结果：把 b64_json 解码为字节写入文件，或下载 url，然后报告保存路径。服务商 URL 可能过期，Base64 也不应留在对话正文里。
2.2 视频
创建端点：POST /v1/videos。查询端点：GET /v1/videos/{id}?model={model}。
| 字段 | 类型 | 说明 |
|---|---|---|
model | string | 必填公共模型 ID。 |
prompt | string | 必填内容描述：主体、动作、场景、镜头、光线和风格。 |
duration | integer | 可选时长，单位秒；允许值由模型决定。 |
resolution | string | 可选输出分辨率，可与比例、时长组合；组合是否可用由模型决定。 |
aspect_ratio | string | 可选宽高比，不是像素尺寸。 |
input_references | array | 可选素材引用，结构同图片接口；仅文生视频时可省略。 |
options | object | 可选服务商扩展选项；seed、negative_prompt、generate_audio 等不是统一字段，只在模型明确支持时传入。 |
callback_url | string | 可选 HTTPS 回调地址；仅在服务商支持回调时可用，网关不主动发送回调。 |
input_references[].role 的取值是 first_frame、last_frame、reference 或 speech。图生视频用 first_frame；首尾帧同时用 first_frame 和 last_frame；参考视频与语音生成需要模型单独支持。一个 source 只能选 url、file 或 data 其中一种。
创建任务的固定返回值（JSON）：
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 以 ioa_v1. 开头的签名任务句柄。必须完整保存，不能换成服务商任务 ID。 |
status | string | queued、running、succeeded、failed、cancelled 或 expired。创建时可能已经是 running。 |
created_at | string | 可选；仅在服务商返回时存在，平台不会生成或换算时间。 |
查询任务的固定返回值（JSON）：
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 任务 ID。 |
status | string | 同上。HTTP 200 不代表生成成功，必须检查此字段。 |
created_at | string | 可选，创建时间。 |
completed_at | string/null | 可选，完成时间；运行中可能省略或为 null。 |
video_url | string/null | 成功后的视频地址；非成功状态通常省略或为 null，有效期由服务商决定。 |
error | object/null | 错误对象或 null，含 code 与 message。 |
Agent 应每 5 秒查询一次，最长等待 10 分钟；只有 queued 和 running 继续等待。succeeded 时立即下载 video_url 到 ./inoneapi-output/ 并报告路径；failed、cancelled 或 expired 时停止并报告 status 与 error，不要自动重新提交。查询时 model 必须与创建请求相同。
2.3 音频
端点：POST /v1/audio/speech。成功响应是音频字节，不是 JSON。
| 字段 | 类型 | 说明 |
|---|---|---|
model | string | 必填公共模型 ID。 |
input | string | 必填非空文本；平台不自动截断、分段或转换 SSML。 |
voice | string/object | 必填音色名，或 {"id":"voice_123"} 自定义音色对象；音色不跨服务商通用。 |
instructions | string | 可选语气、情绪和风格提示，仅支持的模型有效。 |
response_format | string | 可选 mp3、opus、aac、flac、wav、pcm，默认 mp3。 |
speed | number | 可选 0.25–4；省略时由上游决定默认值。 |
stream_format | string | 可选 audio（默认）或 sse；sse 仅用于支持 SSE 的模型。 |
input_references | array | 可选参考素材，结构同图片接口。 |
不要发送 Chat 风格的 stream 字段。音色、输入长度和格式能力取决于模型。
固定返回：
| 条件 | 内容 |
|---|---|
| 2xx | 音频文件字节，直接保存，不要调用 response.json()。 |
| Content-Type | audio/mpeg（mp3）、audio/ogg（opus）、audio/aac（aac）、audio/flac（flac）、audio/wav（wav）或 application/octet-stream（pcm，无容器头）。 |
| 非 2xx | JSON 错误，必须报告状态码和响应体，不能当作音频保存或播放。 |
stream_format=sse | text/event-stream，按服务商事件结构解析，不能把整段 SSE 文本存成 MP3。 |
Agent 要把 input 占位符替换成用户要朗读的文本，按 response_format 选择扩展名保存到 ./inoneapi-output/，并报告路径。指令中的 alloy 只是占位音色；模型拒绝时应询问用户可用音色或报告错误，不要猜测其他音色。
3. 验证调用
先让 Agent 生成一个最小样例，然后到控制台核对该请求的模型 ID、端点、状态、计费和 X-Gateway-Trace-ID。配置阶段不要让 Agent 反复生成。
重试、计费与安全
- 只从
INONEAPI_API_KEY读取 Key，不打印、不写入文件、不提交到仓库。 - 只发送指令列出的字段，不虚构字段，也不照搬其他模型的参数。
- 用户要求未声明的选项时，说明模型不支持，不要发送该字段。
- 只重试网络错误、
408、429和5xx，最多 3 次；429遵循Retry-After。 - 每次成功生成都会计费；每个用户请求只生成一次，不要重复提交测试任务。
- 失败时报告 HTTP 状态、错误 JSON 和
X-Gateway-Trace-ID；视频任务同时报告status和error。 - HTTP 超时不等于未生成，盲目重发可能产生重复计费；当前没有通用幂等保证。
Skill 与 MCP
能力指令就是行为约定：可以放进系统提示词、skill 或工具描述。Agent 支持 MCP 时，可以用 MCP Server 封装相同的端点，但也要在该实现中保留指令里的约束：只用已声明参数、立即保存结果、限制重试、失败不自动重提。
常见问题
401：启动 Agent 的终端没有INONEAPI_API_KEY，或 Key 已被吊销。- 生成字段返回
400：该模型未声明这个参数，删除后重试。 <USER_PROMPT>被原样发送：要求 Agent 替换占位符，并保持 JSON 合法。- Agent 把音频当 JSON 解析：要求它把响应体按字节保存，并检查状态码。
- Agent 只拿到
data[].url却报告找不到图片：要求它立即下载，服务商 URL 可能过期。 - 视频任务一直未完成：到控制台检查任务状态和错误，不要自动重新提交。
- 重复计费：在 Agent 提示词中限制重试次数，每次验证只生成一个样例。