imMAAS API 文档
一个密钥接入 DeepSeek、Kimi、GLM、Qwen、MiniMax、豆包、混元等主流大模型,以及 Seedream 图像生成、Seedance / 可灵 / Wan 视频生成、Embeddings 向量化与 Rerank 重排序能力。全部接口兼容 OpenAI 格式,替换 Base URL 即可无缝迁移。
快速开始
1. 获取 API Key
登录 imMAAS 控制台,在「令牌」页面点击「添加令牌」,创建成功后复制以 sk- 开头的令牌字符串,妥善保存。每个令牌可独立设置额度上限、过期时间与可用分组,建议为不同应用创建独立令牌,便于用量统计与权限隔离。
2. 修改 Base URL
所有请求使用 HTTPS,基础地址:
https://immaas.com/v1
3. 发起第一个请求
curl https://immaas.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-your-api-key" \
-d '{
"model": "deepseek-v4-pro:sjb",
"messages": [{"role": "user", "content": "Hello!"}]
}'from openai import OpenAI
client = OpenAI(
base_url="https://immaas.com/v1",
api_key="sk-your-api-key",
)
resp = client.chat.completions.create(
model="deepseek-v4-pro:sjb",
messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.choices[0].message.content)import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://immaas.com/v1",
apiKey: "sk-your-api-key",
});
const resp = await client.chat.completions.create({
model: "deepseek-v4-pro:sjb",
messages: [{ role: "user", content: "Hello!" }],
});
console.log(resp.choices[0].message.content);base_url 与 api_key 两处即可直接运行,Cherry Studio、NextChat、LobeChat、OneAPI 系客户端同样开箱即用。认证方式
在请求头 Authorization 中携带令牌作为 Bearer Token:
Authorization: Bearer sk-your-api-key
- 令牌即密钥,请勿提交到公开代码仓库或暴露在前端代码中
- 令牌可随时在控制台禁用或删除,禁用后立即失效
- 额度不足时接口返回 402,请及时充值或更换令牌
对话补全(Chat Completions)
POST /v1/chat/completions —— 最核心的接口,用于文本对话、代码生成、推理、翻译、抽取等几乎所有文本任务,支持全部文本模型。
curl -X POST https://immaas.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxx" \
-d '{
"model": "kimi-k3:sjb",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "用一句话介绍量子计算"}
],
"max_tokens": 1024
}'常用参数
| 参数 | 类型 | 说明 |
|---|---|---|
| model | string | 必填。模型名称(含渠道后缀),见下方模型目录 |
| messages | array | 必填。消息数组,支持 system / user / assistant / tool 角色 |
| max_tokens | int | 最大生成 Token 数 |
| temperature | float | 采样温度,0-2,越高越发散 |
| stream | bool | 是否流式返回,见下一节 |
| tools | array | 工具调用(Function Calling)定义 |
流式输出(Stream)
设置 stream: true 后,服务端通过 SSE 逐段返回增量内容,适用于打字机效果与实时交互场景。
from openai import OpenAI
client = OpenAI(base_url="https://immaas.com/v1", api_key="sk-xxx")
stream = client.chat.completions.create(
model="glm-5.3-flash:sjb",
messages=[{"role": "user", "content": "写一首关于春天的诗"}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)查询模型列表
GET /v1/models 返回当前令牌可用分组的全部模型清单,可用于程序化获取模型列表或校验模型名拼写。
curl https://immaas.com/v1/models \ -H "Authorization: Bearer sk-xxx"
/v1/models 返回不一致时,以接口返回和「模型价格页」为准。:sjb / :lv / :whqs / :zzg 等后缀代表不同的上游供应渠道。同名模型(如 kimi-k3:sjb 与 kimi-k3:zzg)能力一致,价格与渠道策略不同,可按需选择;调用时须填写完整名称。DeepSeek 系列
国产开源之光,同等能力下成本最低的第一梯队。
| 模型 | 说明 |
|---|---|
| deepseek-v4-pro:sjb热门 | 旗舰模型,推理与代码能力对标国际第一梯队,价格极优 |
| deepseek-v4-pro-0813:sjb | v4-pro 版本快照(0813),适合需要版本冻结的生产环境 |
| deepseek-v4.1-flash:sjb | 高速版,延迟低吞吐高,适合生产环境大规模部署 |
curl -X POST https://immaas.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxx" \
-d '{"model": "deepseek-v4-pro:sjb", "messages": [{"role": "user", "content": "1+1=?"}]}'Moonshot Kimi 系列
月之暗面旗下模型,超长上下文与智能体能力突出。
| 模型 | 说明 |
|---|---|
| kimi-k3:sjb旗舰 | 开源旗舰,万亿级 MoE,推理与智能体任务全球前列(标准渠道) |
| kimi-k3:whqs | 同款 Kimi K3,经济渠道,价格更低 |
| kimi-k3:zzg | 同款 Kimi K3,超值渠道 |
| kimi-k2.7-code:sjb | 代码特化版,为编程智能体优化 |
| kimi-k2.7-code-highspeed:sjb | 代码特化高速版,批量代码任务提速 |
| kimi-k2.6:sjb | 多模态通用版,均衡主力 |
kimi-k3 提供三个渠道(:sjb / :whqs / :zzg),模型能力完全一致,单价不同,详见价格页。追求稳定选 :sjb,追求性价比选 :zzg。智谱 GLM 系列
智谱 AI 旗下模型,国产开放权重标杆。
| 模型 | 说明 |
|---|---|
| glm-5.3:sjb旗舰 | 当前最新主力,综合能力全面升级 |
| glm-5.3-flash:sjb热门 | 轻量高速版,成本极低,适合高频调用与批量任务 |
| glm-5.2:sjb | 上一代主力,百万上下文,成熟稳定 |
| glm-5.1:sjb | 前代版本,兼容存量项目 |
| glm-5:sjb | GLM-5 初代旗舰,兼容存量项目 |
阿里 Qwen 系列
通义千问全系,多语言与多模态能力全面。
| 模型 | 说明 |
|---|---|
| qwen3.8-max:sjb旗舰 | 通义最新旗舰,深度推理与复杂任务首选 |
| qwen3.8-flash:sjb热门 | 极速版,价格极低,吞吐极高 |
| qwen3.7-max:sjb | 上一代旗舰,复杂任务主力 |
| qwen3.6-plus:sjb | 均衡版,业务主力,性价比高 |
| qwen3.5-plus:sjb | 经典版本,兼容存量项目 |
| qwen3.5-397b-a17b:sjb | 开源版(397B-A17B MoE),可对标自部署行为 |
MiniMax 系列
| 模型 | 说明 |
|---|---|
| minimax-m3:sjb旗舰 | 当前主力,百万上下文,智能体与代码能力强 |
| minimax-m2.7:sjb | 高性价比智能体模型,为 Claude Code / Cursor 等编程工具打造 |
| minimax-m2.7-highspeed:sjb | 高速版,延迟更低 |
字节豆包 Doubao Seed 系列
字节跳动 Seed 系列文本模型,中文场景表现优异。
| 模型 | 说明 |
|---|---|
| doubao-seed-2-1-pro-260628:sjb旗舰 | 当前最新旗舰 Seed 2.1 Pro,推理与写作能力升级 |
| doubao-seed-2.0-pro:sjb | Seed 2.0 主力版本,均衡稳定 |
| doubao-seed-2.0-code:sjb | 代码特化版,编程与重构任务优化 |
腾讯混元系列
| 模型 | 说明 |
|---|---|
| hy4-preview:sjb预览 | 混元最新预览版,能力升级尝鲜 |
| hy3:sjb | 开放权重主力,超低价格,吞吐极高 |
图像生成
POST /v1/images/generations 基于文本描述生成图片,字节 Seedream 系列,同步接口直接返回图片 URL,按张计费。
可用模型
| 模型 | 说明 | 单价 |
|---|---|---|
| doubao-seedream-5-0-pro-260628:sjb热门 | Seedream 5.0 旗舰版,中文语义理解与文字渲染最强 | ¥0.55 / 张 |
| doubao-seedream-5-0-260128:sjb | Seedream 5.0 标准版,速度快价格低 | ¥0.22 / 张 |
curl -X POST https://immaas.com/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxx" \
-d '{
"model": "doubao-seedream-5-0-260128:sjb",
"prompt": "夕阳下的宁静湖泊,远处是连绵雪山",
"size": "1024x1024",
"n": 1
}'视频生成
POST /v1/videos —— 视频生成为异步任务:提交后立即返回 task_id,视频在后台生成(通常 1-5 分钟),通过 GET /v1/videos/{task_id} 轮询获取结果。
可用模型 · 按次计费
| 模型 | 说明 | 单价 |
|---|---|---|
| doubao-seedance-2-5-260628:lv旗舰 | 字节最新视频旗舰,支持参考图/视频/音频,最高 1080p | ¥10 / 次 |
| doubao-seedance-2-0-260128:lv | Seedance 2.0 标准版,画质与运动一致性佳,支持 4K | ¥3 / 次 |
| doubao-seedance-2-0-fast-260128:lv | 2.0 快速版,生成速度更快 | ¥3 / 次 |
| doubao-seedance-2-0-mini-260615:lv热门 | 轻量版,性价比之选,适合批量生成 | ¥3 / 次 |
可用模型 · 按量计费
| 模型 | 厂商 | 说明 |
|---|---|---|
| kling-3.0:sjb | 快手 | 可灵最新旗舰,画质与运动一致性标杆 |
| kling-3.0-turbo:sjb | 快手 | 可灵提速版,速度与成本平衡 |
| kling-3.0-omni:sjb | 快手 | 全能版,多模态输入支持 |
| wan3.0-video:sjb | 阿里 | 通义万相视频生成标准版 |
| wan3.0-video-prime:sjb | 阿里 | 通义万相高质量版 |
| MiniMax-H3:sjb | MiniMax | 高清视频模型,默认 5 秒 1440P |
| happyhorse-1.0:sjb | HappyHorse | 趣味视频生成 |
| happyhorse-1.1:sjb | HappyHorse | 趣味视频生成迭代版 |
import time, requests
BASE = "https://immaas.com/v1"
HEADERS = {"Authorization": "Bearer sk-xxx"}
# 1. 提交视频任务
r = requests.post(f"{BASE}/videos", headers=HEADERS, json={
"model": "doubao-seedance-2-0-mini-260615:lv",
"prompt": "赛博朋克城市夜景,霓虹灯闪烁,电影级画质",
"duration": "5",
})
task_id = r.json()["task_id"]
# 2. 每 5 秒轮询直到完成
while True:
resp = requests.get(f"{BASE}/videos/{task_id}", headers=HEADERS).json()
if resp["status"] == "completed":
print("video:", resp["url"]) # MP4 直链
break
time.sleep(5)Embeddings 向量化
POST /v1/embeddings 将文本转换为向量,是语义搜索、RAG、聚类、去重、推荐系统的基座。兼容 OpenAI Embeddings API。
可用模型
| 模型 | 厂商 | 说明 |
|---|---|---|
| qwen3-embedding-8b:sjb热门 | 阿里 | 开源榜第一梯队,中英文检索俱佳,指令感知,4096 维 |
curl -X POST https://immaas.com/v1/embeddings \
-H "Authorization: Bearer sk-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3-embedding-8b:sjb",
"input": "imMAAS 是一个全球大模型 API 聚合平台"
}'qwen3-embedding-8b:sjb 召回 + bge-reranker-v2-m3:sjb 精排的组合。检索质量不够时,加一层 Rerank 通常比换 Embedding 模型收益更大。Rerank 重排序
POST /v1/rerank 用交叉编码器对「查询 + 候选文档列表」逐一精排,返回按相关度排序的结果。在向量召回之后加一层 Rerank,通常可再提升 2-5 个点的检索精度,是 RAG 精排标准组件。
可用模型
| 模型 | 厂商 | 说明 |
|---|---|---|
| bge-reranker-v2-m3:sjb热门 | 智源 BAAI | 开源多语言重排序标杆,中文检索增益明显,价格友好 |
curl -X POST https://immaas.com/v1/rerank \
-H "Authorization: Bearer sk-xxx" \
-H "Content-Type: application/json" \
-d '{
"model": "bge-reranker-v2-m3:sjb",
"query": "如何降低 API 调用成本",
"documents": [
"imMAAS 按 token 计费,充值即用",
"人民币直充无需境外信用卡",
"多渠道冗余保障服务可用性"
],
"top_n": 3
}'{
"results": [
{"index": 0, "relevance_score": 0.92},
{"index": 1, "relevance_score": 0.31},
{"index": 2, "relevance_score": 0.05}
]
}计费说明
- 按 Token 计费:文本、Embeddings 与 Rerank 模型按处理 Token 数计费,单价见「模型价格页」
- 图像按张计费:Seedream 标准版 ¥0.22/张、旗舰版 ¥0.55/张
- 视频按次 / 按量计费:Seedance 系列 ¥3 或 ¥10/次;可灵、Wan、MiniMax-H3、HappyHorse 按量计费,单价见价格页
- 人民币直充:支持支付宝 / 微信扫码充值,即时到账,无需境外信用卡
- 额度透明:控制台「数据看板」实时展示各模型用量与消费明细,令牌余额随时可查
- 失败不扣费:视频等异步任务采用「预冻结 + 成功结算」,失败自动全额退款;接口报错不产生扣费
错误码
| 状态码 | 含义 | 处理建议 |
|---|---|---|
| 400 | Invalid Request · 请求格式错误 | 检查参数名、类型与 JSON 格式 |
| 401 | Unauthorized · 令牌无效或缺失 | 检查 Authorization 头与令牌状态 |
| 402 | Insufficient Quota · 额度不足 | 充值或更换有余额的令牌 |
| 404 | Model Not Found · 模型不存在 | 核对模型名(含渠道后缀),或确认令牌分组包含该模型 |
| 429 | Rate Limit · 请求过于频繁 | 降低并发与频率,指数退避重试 |
| 500 | Internal Error · 服务端异常 | 稍后重试;持续出现请联系客服 |
常见问题
和直接调用各家官方有什么区别?
接口格式完全一致,区别在于:一个密钥调用全部主流模型、统一账单与用量看板、人民币直充无需逐一注册各家账号与支付方式、出问题有中文客服响应。模型均为上游正规渠道,不降智、不阉割。
模型名里的 :sjb / :lv 后缀是什么意思?
后缀是上游供应渠道的标识,同名模型不同渠道能力一致、价格与策略不同(如 kimi-k3:sjb / kimi-k3:zzg)。调用时需填写完整名称(含后缀),完整列表以 GET /v1/models 返回为准。
支持哪些客户端?
所有兼容 OpenAI 格式的客户端均可使用:Cherry Studio、ChatBox、NextChat、LobeChat、Open WebUI、沉浸式翻译、各类编程 Agent 等,只需填入 Base URL 和令牌。
是否支持工具调用 / 视觉输入 / JSON Mode?
支持。只要对应模型官方支持该能力,通过 imMAAS 调用同样支持,参数格式与 OpenAI 一致。
视频任务失败会扣费吗?
不会。视频等异步任务采用「预冻结 + 成功结算」机制:提交时按最坏情况预冻结额度,任务失败自动全额解冻退款,实际费用按成功结果结算、多退少补。
数据安全如何保障?
全程 HTTPS 传输;对话内容仅用于本次请求转发,不留存、不用于训练;渠道密钥与用户令牌隔离存储。
余额 / 令牌可以转让吗?
账户余额不可转让;令牌可禁用、删除,消费明细单独统计。
后续还会上线哪些能力?
TTS 语音合成、STT 语音识别、实时语音对话、音乐生成等能力正在规划接入中。有具体需求欢迎联系客服提报,我们会按需求优先级评估上架。
联系我们
接入遇到问题、需要技术咨询、模型上架建议,欢迎随时联系:
- 客服微信:13671036992(充值 / 接入 / 报价,通常 30 分钟内响应)
- 企业微信:扫码添加,右侧公众号菜单同样可以找到我们