📖 API文档

大西瓜API 提供与 OpenAI 兼容的 文本对话与图像 / 视频 / 音乐生成接口。文本对话提供同步 / 异步两种端点、流式 / 非流式两种模式，支持多轮上下文、多模态（图文）消息、函数调用（tools）、思考强度控制与采样参数透传，并可用「渠道前缀」精确指定供给渠道；图像/视频/音乐生成也支持文生图、图生图、异步任务轮询，并与文本接口一致，可用「渠道ID/模型名」前缀强制指定供给渠道。第三方应用、开源项目、WorkBuddy 等客户端可用 OpenAI 兼容方式直接对接。

🔑 认证方式

所有 API 请求在 HTTP 头中携带 API 密钥：

Base URL：https://image.wxfl.mobi/v1

💬 文本对话（Chat Completions）

提供与 OpenAI Chat Completions 完全兼容的文本对话接口，支持多轮上下文、流式输出（SSE）、多模态（图文）消息、函数调用（tools）与思考强度控制。把 OpenAI SDK 的 base_url 指向本站即可无缝接入。提供同步、异步两个端点：

主要请求参数

可选透传的采样参数

以下 OpenAI 兼容参数，只要调用方显式给出即原样透传上游；未传则保持上游默认，站点不主动注入：

渠道前缀：精确指定供给渠道（重要）

同名模型可能由多个渠道供给（例如 gpt-6.1-sol 同时存在于 mi、codex 福利 / 企业 / 满血等渠道）。直接写模型名时平台自动路由；若要强制走某个渠道，在 model 前加 渠道ID/ 前缀：

服务端按首个 / 拆分：前段为纯数字则识别为渠道 ID，后段作为纯模型名转发。不带前缀时按平台调度自动选择可用渠道。

可用文本渠道与模型清单（共 14 个渠道）

非流式请求（curl）

curl -X POST https://image.wxfl.mobi/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3-flash",
    "messages": [
      {"role": "system", "content": "你是一个乐于助人的助手"},
      {"role": "user", "content": "用一句话介绍你自己"}
    ],
    "stream": false
  }'

非流式响应示例

{
  "id": "chat_xxx",
  "model": "glm-5.3-flash",
  "choices": [
    {"index": 0, "message": {"role": "assistant", "content": "你好！我是……"}, "finish_reason": "stop"}
  ],
  "usage": {"prompt_tokens": 16, "completion_tokens": 5, "total_tokens": 21}
}

流式请求（SSE）

curl -N -X POST https://image.wxfl.mobi/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [{"role": "user", "content": "写一句晚安"}],
    "stream": true
  }'

流式以 data: {...} 逐行返回增量内容（choices[0].delta.content），结束前返回带 usage 的分片，最后以 data: [DONE] 结束。推理模型（deepseek / glm）的思考过程通过 delta.reasoning_content 原样透传，思考内容不计入正文输出计费。

多轮对话

把历史 user / assistant 消息按顺序放进 messages，模型即可保持上下文：

"messages": [
  {"role": "user",      "content": "帮我写一首伤感的流行歌"},
  {"role": "assistant", "content": "《灯还亮着》……"},
  {"role": "user",      "content": "把副歌改得更释然一些"}
]

Python（OpenAI SDK）示例

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxx",
    base_url="https://image.wxfl.mobi/v1",
)

resp = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[{"role": "user", "content": "你好"}],
    stream=False,
)
print(resp.choices[0].message.content)
print(resp.usage)

多模态（图文）消息

消息的 content 可传分段数组，混合文本与图片。平台会统一提取其中的文本，图片段按 OpenAI image_url 结构透传（请确认所用模型 / 渠道支持视觉）：

{
  "model": "claude-sonnet-5",
  "messages": [
    {"role": "user", "content": [
      {"type": "text", "text": "这张图里写了什么？一句话回答"},
      {"type": "image_url", "image_url": {"url": "https://example.com/shot.png"}}
    ]}
  ]
}

函数调用（Function Calling）

传入 tools 定义工具，模型在需要时通过 tool_calls 下发调用指令；平台与模型不执行函数，具体调用由客户端完成，再把结果作为 role: "tool" 消息回传以继续对话。

{
  "model": "gpt-6.1-sol",
  "messages": [{"role": "user", "content": "南宁现在天气怎么样？"}],
  "tool_choice": "auto",
  "tools": [
    {"type": "function", "function": {
      "name": "get_weather",
      "description": "查询指定城市的当前天气",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string", "description": "城市名"}},
        "required": ["city"]
      }
    }}
  ]
}

模型响应的 message 中会带 tool_calls：

"message": {
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {"id": "call_abc", "type": "function",
     "function": {"name": "get_weather", "arguments": "{\"city\": \"南宁\"}"}}
  ]
}

思考强度（reasoning_effort）

用 reasoning_effort 控制推理模型的思考投入。调用方显式指定时优先采用；非 GLM 系列原样透传，GLM 系列仅支持 low / high / max，平台会把 minimal / none / disabled 折算为 low、medium 折算为 high，避免上游报错。未指定时平台按任务难度与输出长度自动判断。

{
  "model": "deepseek-v4.1-flash",
  "messages": [{"role": "user", "content": "证明根号2是无理数"}],
  "reasoning_effort": "high"
}

异步对话（Async）

异步端点的请求体与同步端点完全一致（同样支持渠道前缀、多模态、tools、采样参数），提交后立即返回，后台线程处理，适合不希望长连接等待的场景。

curl -X POST https://image.wxfl.mobi/v1/chat/completions/async \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "25/deepseek-v4.1-flash",
    "messages": [{"role": "user", "content": "写一篇两千字的短文"}]
  }'

提交成功立即返回（此时已按预估费用冻结余额）：

{
  "success": true,
  "task_id": "chat_1793456789a1b2c3",
  "status": "running",
  "message": "任务已创建，正在后台处理"
}

🧩 WorkBuddy 对接指南

WorkBuddy 是一个 OpenAI 兼容的客户端 / 连接器，通过本平台统一接入各家大模型，并在客户端侧完成多模态消息组装与函数（工具）执行。平台后端已针对 WorkBuddy 的消息形态与调用方式做了完整兼容，按下表配置即可对接，无需额外适配。

一、基础连接配置

二、平台已兼容的 WorkBuddy 能力

三、对接请求示例

curl -X POST https://image.wxfl.mobi/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "25/deepseek-v4.1-flash",
    "messages": [
      {"role": "system", "content": "你是 WorkBuddy 的助手"},
      {"role": "user", "content": [
        {"type": "text", "text": "读取这张图并调用工具汇总"}
      ]}
    ],
    "stream": true,
    "tools": [
      {"type": "function", "function": {
        "name": "summarize",
        "description": "汇总内容",
        "parameters": {"type": "object", "properties": {"text": {"type": "string"}}}
      }}
    ],
    "tool_choice": "auto",
    "reasoning_effort": "medium"
  }'

💰 查询账户余额

携带 API 密钥查询该密钥所属账户的余额（元）。

curl https://image.wxfl.mobi/api/v1/balance \
  -H "Authorization: Bearer sk-xxxxxxxx"

# 返回示例
# {"balance": 6.39, "quota": 100000000, "used_quota": 0}

🖼️ 文生图 / 图生图

请求参数

渠道前缀：强制指定供给渠道（图片/视频通用）

和文本接口一致，同名模型多渠道时，在 model 前加 渠道ID/ 即可强制走指定渠道；服务端会自动剥掉前缀，实际转发上游仍使用纯模型名。

不带前缀时继续按平台自动路由；令牌若已绑定渠道，前缀必须与令牌渠道一致。

文生图请求示例

图生图请求示例

gpt-image-2.5 系列请求示例

异步响应示例（提交成功）

🔄 查询异步任务结果

用提交时返回的 task_id 轮询任务状态，直到 status 为 completed 即可拿到图片 URL。

请求示例

完成响应示例

📋 模型列表

获取当前已开放的全部模型列表（含文本、图片、视频、音乐）。其中文本模型用于 /v1/chat/completions，其余用于生成接口。

🎯 模型可用性与分档计费（重要）

本站采用白名单机制：只有已配置价格的「模型 + 档次」才会开放调用；未配置价格的模型或档次，即使支持也会被拦截，返回 404 model_not_found，不会生成、不会扣费。模型广场与站内 AI 生图也只展示已开放的模型。

三种指定模型 / 档次的方式

🚦 错误码

💰 模型与价格

⚠️ 各渠道注意事项

异步接口（需轮询）

• 异步任务，返回 task_id，需轮询查询
• size 支持比例字符串（1:1、9:16 等）和像素格式
• 任务查询端点统一用 GET /v1/videos/generations/{task_id}，兼容 GET /v1/video/generations/{task_id}
• 图生图参数 image_urls 为 URL 数组
• 多档模型需在 model 名后加 -1k / -2k / -4k 后缀区分分辨率档位

同步接口（直接返回）

• 同步返回，POST 后直接返回图片数据（b64_json），无需轮询
• 图生图时自动下载 image_urls 图片并转发
• size 建议用像素格式（1024x1024）

🐍 Python 调用示例

\U0001f3ac 文生视频 / 图生视频

视频提交接口为 POST /v1/videos/generations，同时兼容部分软件使用的单数路径 POST /v1/video/generations；通过 model 参数指定视频模型即可。默认按同步模式等待任务完成并直接返回完整视频地址；需要异步轮询的客户端可显式传 "async": true 或 "wait": false。

请求地址

参数说明

yy 渠道固定参数模型

这两个模型在服务端锁死分辨率和时长；size 仅用于推导竖屏/横屏，多余参考图会被 400 拦截。推荐调用：28/firefly-veo31-lite 或 28/muse-video-cdn。

文生视频请求示例

curl -X POST https://image.wxfl.mobi/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "28/firefly-veo31-lite",
    "prompt": "一艘红色玩具帆船在平静水面上摇晃，固定镜头，自然光",
    "size": "9:16"
  }'

图生视频请求示例

curl -X POST https://image.wxfl.mobi/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "28/muse-video-cdn",
    "prompt": "参考图中的小猫转身看镜头，固定镜头",
    "size": "16:9",
    "image_urls": ["https://example.com/reference.jpg"]
  }'

同步完成响应（默认）

{
  "id": "task_abc123",
  "task_id": "task_abc123",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "url": "https://image.wxfl.mobi/static/generated/video/video_abc.mp4",
  "video_url": "https://image.wxfl.mobi/static/generated/video/video_abc.mp4",
  "content_url": "https://image.wxfl.mobi/static/generated/video/video_abc.mp4",
  "data": [
    {"object": "video", "url": "https://image.wxfl.mobi/static/generated/video/video_abc.mp4"}
  ]
}

异步提交响应（显式 async=true）

{
  "task_id": "task_abc123",
  "status": "RUNNING",
  "model": "firefly-veo31-lite"
}

\U0001f3b5 文生音乐（AI生歌）

使用 POST /v1/images/generations，指定音乐模型即可；同名模型多渠道时同样可用 渠道ID/模型名 前缀强制指定渠道。音乐生成约需 1-3 分钟。

参数说明

请求示例

curl -X POST https://image.wxfl.mobi/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YuE2",
    "prompt": "[verse]\n阳光洒满操场\n笑声回荡在角落\n[chorus]\n青春永远不会散场"
  }'

📡 图片 / 视频 / 音乐渠道与模型清单

调用同名模型时，可按上方“渠道ID/模型名”前缀强制走对应渠道；下表为当前配置快照，实时可用模型请以 GET /v1/models 和模型广场为准。

❓ 常见问题

1. 如何获取 API 密钥？

登录后进入 API令牌 页面，点击"创建令牌"即可获取。

2. 提交后多久能拿到图片？

F接口和T接口为异步任务，通常 10-60 秒完成，用 task_id 轮询即可。TT接口同步返回，请求后直接拿到图片。

3. 图生图怎么用？

在请求中加 image_urls 参数（参考图 URL 数组），自动下载并适配格式。渠道 3 tt-image-2 最多 14 张；渠道 6、7 带参考图时由网关自动转 multipart edits；其他已验证模型最多 16 张。Agnes 渠道当前密钥无效，上限待确认。

生成图存储：无论上游返回 URL 还是 b64_json，网关都会把生成图保存到数据盘 /data/unified-api/static/generated/image，最终只返回 https://image.wxfl.mobi/static/generated/image/... 本机地址。

4. 调用失败会扣费吗？

不会，只有成功生成才扣费。轮询到失败会立即自动退款；即使你提交后不主动查询，平台也会每 60 秒主动核对在途任务，对失败或超时（约 30 分钟仍无结果）的任务自动退款，款项原路退回账户余额，可在「余额流水」中查看。

5. 余额不足怎么办？

请联系管理员充值，或在个人中心查看充值方式。余额不足时调用会被拦截并返回错误。

6. 为什么返回 404 model_not_found？

说明该模型或你指定的档次未开放。多档模型请在模型名后加 -1k/-2k/-4k 后缀，调用前可先通过 GET /v1/models 或模型广场确认当前可用的模型与档次。