API 端点

从首页接入

打开 /，比较当前 Token 价格。价格单位为每一百万 Token 的 USD 费用。页面可见且在线时，每 30 秒刷新价格。暂停模型轮播以查看报价。刷新失败时，页面保留上次价格，并明确提示数据可能过期。

在接入示例中选择 Responses、Chat Completions 或 Messages。复制命令，将示例模型替换为可用模型，并设置 API Key。页面不会发送请求。示例使用已配置的 Base URL；无法确定安全的 Base URL 时，复制按钮不可用。打开 /apidocs 查看其他协议和语言示例。

基础 URL 与认证

将请求发送到 Monoize 的监听地址。默认为 http://localhost:8080。使用以下任一请求头携带 API 密钥：

Authorization: Bearer sk-...
# 或
x-api-key: sk-...

下列每个端点都有 /api 前缀别名，例如 /api/v1/chat/completions。当客户端硬编码了 /api 路径时使用别名。同步推理客户端可以省略 /v1，例如 /responses。视频端点必须保留 /v1。

同步推理端点可以访问兼容的推理上游。视频生成使用下文的独立异步接口。例如，客户端调用 /v1/messages，而路由通过 chat_completion 类型的 Channel 服务该模型。Monoize 在两个方向上转换协议。

协议转换

当多个工具使用相同名称时，请使用 Responses 工具名称空间。所选 Channel 使用 Chat Completions、Messages 或 Gemini 时，Monoize 会保留工具身份。

跨服务商传递文件时，请提供文件内容或公开 URL。私有文件引用必须匹配唯一的 Provider、Channel 和凭证范围。

请将图片蒙版与原图一起提交。图片转换会保留蒙版尺寸和透明度。

目标协议无法表示响应中的媒体时，接口会返回明确错误。流式响应会以错误结束，不会发送成功结束事件。

Gemini 转换会保留受支持的采样参数、引用、工具签名和用量明细。协议专属字段只会发送到兼容的目标协议。

Chat 路由会保留 OpenRouter 的 configuration_update 消息，包括空内容更新。文件 data URI 转为 Messages 文档时会保留 MIME 类型。Messages 流会保留 citations_delta 引用。Responses 内容过滤终止会保留为未完成状态，不会误报为长度限制。

Chat 与 Responses 会将支持的 URL 引用转换为目标格式。无法表示的引用位置仅在原协议中保留。Token logprobs 与对应文本关联；文本修改后，不再匹配的概率会被丢弃。Responses 失败终态保留部分输出、用量和错误详情。Chat 与 Messages 将失败或取消状态输出为错误。Messages 保留暂停、压缩和上下文限制的停止原因。计费包含上游报告的所有压缩迭代，不会重复计算主生成用量。

协议转换分别保留 raw 推理、可读摘要和不透明的回传载荷。删除 raw 推理后，不会用摘要恢复它。Messages 的 thinking 文本映射为摘要，signature 保持不透明。非法流生命周期和格式错误的已知事件会返回错误。完整 Messages 请求和响应拒绝截断的工具 JSON；原生 max_tokens 流可保留未完成的参数字节。

Chat 中具有相同稳定身份的推理分片会累计到同一节点。最终快照只补充尚未发送的文本后缀，独立的 detail 保持分离。

工具参数可以实时输出。工具签名信封等待工具终态确定后再输出，签名始终作为完整的不透明值处理。

Messages 请求会一起转换带对象 input_schema 的 custom 工具、JSON 对象调用参数和关联结果，并保留 call_id。无效的 schema 或参数会返回错误。

Responses 对象包含非 null 的 error 且缺少有效 status 时会返回错误。空对象会被拒绝。没有错误且包含 output 数组的兼容响应仍可省略 status。

列出模型

curl http://localhost:8080/v1/models \
  -H "Authorization: Bearer sk-..."

响应以 OpenAI 列表格式返回调用密钥可用的逻辑模型。

Chat Completions

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "messages": [{ "role": "user", "content": "Hello" }],
    "stream": true
  }'

设置 "stream": true 使用服务器推送事件。省略或设为 false 则返回单个 JSON 响应。

Responses

curl http://localhost:8080/v1/responses \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "input": "Hello",
    "stream": true
  }'

说明：

将返回的 Monoize 响应 ID 用作 previous_response_id。Monoize 在本地解析保存的规范历史。
历史属于同一租户和 API key。将续接请求发送到同一个 Monoize 进程。历史在 30 分钟后或缓存淘汰时失效。重启会清除历史。
Responses 请求默认使用 store=true。设置 store=false 可停止保存历史。未知或不可用的 ID 返回 400 previous_response_not_found。
仅将 conversation 用于原生 Responses 状态。不要同时使用 conversation 和 previous_response_id。
GET /v1/responses 会升级为 WebSocket 传输，供使用该传输的客户端调用。
WebSocket v1 客户端收到 response.done。WebSocket v2 客户端收到 response.completed。
GET /v1/codex/responses 与 GET /v1/responses 使用同一个 WebSocket 处理器。POST /v1/codex/responses 与 POST /v1/responses 使用同一个 HTTP 处理器。两个路径也有 /api 别名。
POST /v1/responses/compact 压缩一段会话。
Monoize 将原生 compact 请求体转发到上游 POST /v1/responses/compact。
选定 Channel 后，如果该 Channel 映射了 {model}-openai-compact，Monoize 把线路模型改成这个兄弟模型。否则发送会话模型。
计费使用会话模型的价格。兄弟模型 ID 不需要单独的价格记录。

向 Responses 上游转发请求时，Monoize 保留显式传入的 include 和 reasoning.summary。它不会自动添加 reasoning.encrypted_content 或默认摘要设置。

关闭推理

在 Chat Completions 请求中设置 "reasoning_effort": "none"。在 Responses 请求中设置 "reasoning": { "effort": "none" }。

Monoize 会向 OpenAI 兼容上游保留显式 none。如果 Chat 请求保留了原生 reasoning 对象，Monoize 会在该对象中写入 effort: "none"，不再发送顶层简写字段。

如果没有显式 Messages 控制参数，Monoize 会向 Messages 上游发送 thinking: { "type": "disabled" }。Gemini 上游收到 generationConfig.thinkingConfig.thinkingBudget: 0。

DeepSeek Chat 请求会直接透传推理努力值，不做数值映射，也不自动生成 thinking 控制参数。

省略推理力度会允许上游使用默认值。请选择支持关闭推理的模型。强制推理的模型无法满足此请求。

Anthropic Messages

curl http://localhost:8080/v1/messages \
  -H "x-api-key: sk-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

客户端省略输出上限时，Messages 上游请求使用 max_tokens: 128000。显式上限保持原值。

Gemini 上游

将 Channel 的上游类型设为 gemini，即可通过现有端点使用 Gemini。此支持不新增公开的 Gemini HTTP 端点，也不包含 Live API。

Monoize 双向转换 generateContent 请求、响应和对话历史。流式响应使用 streamGenerateContent SSE。

文本、推理、函数调用、函数结果和支持的媒体保留顺序与标识。思考签名始终关联原始 Part。
生成控制参数、结构化响应格式、工具和工具选择转换为目标协议支持的对应字段。
Token logprobs 始终关联匹配的文本。文本变更后会丢弃失效的分数。Gemini 最多允许请求 20 个 top logprobs。
可表示的引用和 grounding 来源链接转换为目标格式。引用范围保留文本中的位置，包括非 ASCII 文本。
文本和推理在完成前持续输出。需要完整内容的媒体和带签名的 Part 可以等到完成后输出。失败或截断的流返回错误。
Monoize 优先返回 index 为 0 的候选响应，否则返回第一个候选响应。独立候选响应不会合并。

Gemini 专属工具、Provider 执行的代码和无法转换的元数据仅在 Gemini 内保留。目标协议只接收其能够表示的功能。

Embeddings

curl http://localhost:8080/v1/embeddings \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-embedding-model",
    "input": "The quick brown fox"
  }'

图像

设置 stream: true 和 n: 1，接收完成事件 SSE。流返回完成的图片或错误，最后发送 [DONE]。接口不发送局部预览。省略 stream 可保持 JSON 响应。

通过 Responses Channel 调用图像接口前，请配置 image_enable_openai_generation_tool。缺少所需工具时，请求会在转发前返回错误。

生成：

curl http://localhost:8080/v1/images/generations \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-image-model",
    "prompt": "A lighthouse at dawn",
    "size": "1024x1024"
  }'

使用 multipart/form-data 上传图片文件：

curl http://localhost:8080/v1/images/edits \
  -H "Authorization: Bearer sk-..." \
  -F model="my-image-model" \
  -F prompt="Add a red boat" \
  -F 'image[]=@input.png'

添加 -F mask=@mask.png 可使用 PNG 蒙版。编辑请求接受 1–16 张源图片和最多一个蒙版。

使用 JSON 提交图片引用：

curl http://localhost:8080/v1/images/edits \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-image-model",
    "prompt": "Add a red boat",
    "images": [{ "image_url": "https://example.com/input.png" }],
    "mask": { "image_url": "https://example.com/mask.png" }
  }'

每个 images 条目和可选的 mask 对象必须恰好包含一个 image_url 或 file_id。image_url 接受 HTTP(S) URL 或 Base64 数据 URL。文件 ID 必须能通过所选上游凭据访问。文件 ID 不会在上游账号或 Provider 之间转移文件。

两个端点都要求提供 model 和 prompt。非流式请求的 n 仍会拆分为独立子请求。设置 stream=true 和 n=1 可接收图像 SSE 事件。原生 openai_image 路由将内联图片作为 multipart 发送。只要任一输入或蒙版保留 HTTP(S) URL 或文件引用，该路由就使用 JSON。

设置 stream=true 后，Monoize 立即发送 SSE 保活注释，并在连续 15 秒没有数据事件时再次发送。OpenRouter 图片编辑自动使用非流式上游请求；其他路由收到明确拒绝流式的 HTTP 400 或 422 后，只回退一次。JSON 图片响应转换为完成事件，不会伪造预览图。计费和日志仍计为一次流式请求，普通网络错误不会触发此回退。这可以在生成期间保持下游连接，但不会延长上游请求超时。

对于 Responses 路由，配置 image_enable_openai_generation_tool。请求中的图像参数优先于变换默认值，蒙版会映射到工具的 input_image_mask。图像 background 用于配置工具，与 Responses 的布尔值 background 不同。Responses 路由会明确拒绝图像 style 和 response_format="url"。

图像响应保留上游返回的 quality、size、background、output_format 和图像 model。上游未返回的值保持缺省；请求参数不能证明上游的实际执行结果。返回多张图像时，只有所有图像都报告相同值，响应才会包含对应的顶层字段。图像流的完成事件携带各自图像的元数据。

OpenRouter 图像上游

通过 Provider API 将内嵌 Channel 的类型设为 openrouter_image。Base URL 使用 https://openrouter.ai/api。

将逻辑模型映射到 OpenRouter 模型标识。Monoize 将生成和编辑请求发送到 /v1/images。模型发现和模型列表健康检查使用 /v1/images/models。

参考图像支持 URL 和内联 Base64 数据。不支持蒙版和私有文件 ID。

图像编辑使用非流式上游请求。下游流式连接通过 SSE 心跳保持活动。

使用官方 SDK

将官方 SDK 的基础 URL 指向 Monoize：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-...",
)

import anthropic

client = anthropic.Anthropic(
    base_url="http://localhost:8080",
    api_key="sk-...",
)

错误响应

HTTP 状态码	错误码	含义
`401`	`unauthorized`	API 密钥缺失、无效、被禁用或已过期
`402`	`insufficient_balance`	用户或子账户余额不足
`402`	`api_key_spend_limit_reached`	密钥的消费限额窗口(总额、每小时或每日)已用尽
`403`	`model_not_allowed`	密钥的模型限制拒绝了请求的模型
`403`	`ip_not_allowed`	客户端 IP 不在密钥的 IP 白名单中
`404`	`model_not_found`	当前账户类别没有此模型
`503`	`no_healthy_upstream`	模型存在，但没有符合条件的健康路由
`502`	`upstream_error`	所有已尝试的上游路由均失败

上游错误文本在到达客户端之前会被脱敏。完整详情请在请求日志中查看。

异步视频生成

选择 seedance 或 minimax_video Channel。向主节点发送视频请求。副本节点返回 503 video_primary_required。

curl http://localhost:8080/v1/videos \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-order-001" \
  -d '{"model":"my-video-model","prompt":"A cat walks through a garden","duration":6,"resolution":"720p"}'

curl http://localhost:8080/v1/videos/video_TASK_ID \
  -H "Authorization: Bearer sk-..."

创建成功返回 HTTP 202、video_ 任务 ID 和 Location。使用同一个 API Key，每五秒查询一次该地址。服务重启后任务仍然保留。

每次生成使用唯一的 Idempotency-Key。重试同一个请求时复用此值。同一个值对应不同请求时返回 409。

状态包括 queued、submitting、running、succeeded、failed、cancelled 和 unknown。成功后及时下载 output.url。上游链接会过期。Monoize 不托管视频文件。

unknown 表示上游可能仍有任务。创建替代任务前联系管理员。Monoize 不会自动重新提交结果不明确的创建请求。

使用 GET /v1/videos?limit=20&after=video_TASK_ID 分页查询。通过 has_more 和 next_cursor 读取下一页。每个 API Key 只能访问自己创建的任务。

使用 POST /v1/videos/{id}/cancel 取消尚未开始提交的任务。开始提交后返回 409。HTTP 错误使用标准 Monoize 错误格式。生成失败的信息在任务的 error 中。

可选字段为 duration（1–60 秒）、resolution、aspect_ratio、input 和 provider_options。模型的具体限制由上游验证。未知顶层字段返回 400。请求体上限为 1 MiB。

图生视频示例："input":[{"type":"image","url":"https://example.com/frame.jpg","role":"first_frame"}]。输入必须使用 HTTP(S) URL。类型也支持 video 和 audio。参考素材角色为 reference_image、reference_video 和 reference_audio。最多传入 50 个素材。

MiniMax v1 支持文本、首帧和尾帧图片，不支持参考素材或 aspect_ratio。H3 使用 v2，默认时长为 6 秒，分辨率为 768P。纯文本默认比例为 16:9，其他输入默认为 adaptive。

Seedance 的 provider_options 支持 seed、generate_audio、watermark、camera_fixed、return_last_frame、service_tier、execution_expires_after 和 output_format。MiniMax v1 支持 prompt_optimizer 和 fast_pretreatment。MiniMax v2 支持 extra。不支持客户端回调。

创建时预扣固定价格。成功后结算一次，明确失败或提交前取消时退款一次。查询错误和结果不明确时保留预扣。任务的 billing 返回冻结价格、实际扣费和计费状态。这些任务不进入同步请求日志。

API 端点

从首页接入Copy Anchor Link

基础 URL 与认证Copy Anchor Link

协议转换Copy Anchor Link

列出模型Copy Anchor Link

Chat CompletionsCopy Anchor Link

ResponsesCopy Anchor Link

关闭推理Copy Anchor Link

Anthropic MessagesCopy Anchor Link

Gemini 上游Copy Anchor Link

EmbeddingsCopy Anchor Link

图像Copy Anchor Link

OpenRouter 图像上游Copy Anchor Link

使用官方 SDKCopy Anchor Link

错误响应Copy Anchor Link

异步视频生成Copy Anchor Link

本页目录