把创作模型接入你的应用

基础地址：https://api.mumoo.cc。文本、图片、视频和音频使用同一账号与额度，不同能力使用对应接口和参数。

1. 注册或登录 MUMOO，在控制台创建独立的应用密钥，设置额度上限、有效期与模型权限。
2. 通过 GET /v1/models 获取该密钥实际可调用的模型 ID，再通过 GET /v1/mumoo/models 读取对应接口、参数能力和账号价格。使用返回的 id，不要把显示名称当成 ID。
3. 在服务端保存密钥，先调用查询接口确认权限，再按所选模型提交生成。

curl https://api.mumoo.cc/v1/models \
  -H "Authorization: Bearer $MUMOO_API_KEY"

curl https://api.mumoo.cc/v1/mumoo/external-policy \
  -H "Authorization: Bearer $MUMOO_API_KEY"

本页与 OpenAPI 无需登录。模型权限、准确价格及历史账单需使用自己的账号或密钥查看。

选模型，也选对应接口

同类模型也可能有不同的时长、尺寸、参考数量和输出格式。模型列表的 supported_endpoint_types 用于辨认接口族，具体档位以模型详情和当前价格页为准。替换 model 前应同时核对这些参数。

GET /v1/mumoo/models/{model_id} 返回该型号的 capabilities、variants[].endpoint、variants[].when、variants[].request_schema 和 prices。目录自动沿用当前已发布版本、启用线路及本密钥的分组和模型权限；隐藏、停用或仅供旧任务恢复的型号不再供新请求选择。需要刷新目录时比较 revision。画布界面的档位名称保留在 capabilities，实际请求字段以对应 variant 为准。

可以复制的服务端示例

自行设置环境变量 MUMOO_API_KEY 和 MUMOO_MODEL_ID。示例不会自动发送请求。

import os, uuid
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MUMOO_API_KEY"],
    base_url="https://api.mumoo.cc/v1",
    max_retries=0,
)
# 在应用任务里持久保存此编号；同一任务的重试使用同一个编号。
job_key = str(uuid.uuid4())
reply = client.chat.completions.create(
    model=os.environ["MUMOO_MODEL_ID"],
    messages=[{"role": "user", "content": "用一句话描述清晨的竹林"}],
    extra_headers={"Idempotency-Key": job_key},
)
print(reply.choices[0].message.content)
print(reply._request_id)

const headers = { Authorization: `Bearer ${process.env.MUMOO_API_KEY}` };
for (const path of ["/v1/models", "/v1/mumoo/external-policy"]) {
  const response = await fetch(`https://api.mumoo.cc${path}`, {
    headers, signal: AbortSignal.timeout(15000),
  });
  console.log(response.status, await response.json());
}

可下载的轻量客户端

Python 客户端 · Node.js 客户端。均只使用标准库或运行时自带功能；导入文件不会发送请求。生成函数要求传入已保存的业务编号，只对查询进行有限重试，不会自动重提生成。

from mumoo_client import MUMOOClient
client = MUMOOClient()
catalog = client.models()
# 先选择目录中的型号、endpoint 及参数；使用应用数据库中已保存的任务编号。
result = client.generate(
    "/v1/images/generations",
    {"model": "gpt-image-2", "prompt": "白色背景上的蓝色立方体", "n": 1},
    business_id="my-app:image-job-001",
)
print(result["request_id"], result["receipt_id"])

流式返回、参考素材和其他能力

# 流式文本；同一业务任务始终复用同一个 Idempotency-Key。
curl -N https://api.mumoo.cc/v1/chat/completions \
  -H "Authorization: Bearer $MUMOO_API_KEY" \
  -H "Idempotency-Key: my-app:text-job-001" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-luna","messages":[{"role":"user","content":"你好"}],"stream":true}'

# 上传参考素材；读取响应里的文件地址后，再按型号要求放入生成参数。
curl https://api.mumoo.cc/v1/files \
  -H "Authorization: Bearer $MUMOO_API_KEY" \
  -F "file=@reference.png" -F "purpose=assistants"

# 视频（需要密钥具有该型号所在分组的权限）。
curl https://api.mumoo.cc/v1/videos \
  -H "Authorization: Bearer $MUMOO_API_KEY" \
  -H "Idempotency-Key: my-app:video-job-001" \
  -H "Content-Type: application/json" \
  -d '{"model":"wan-3","prompt":"蓝色小球缓慢滚动","duration":2,"resolution":"480p","aspect_ratio":"16:9"}'

# 配音；普通 speech 接口返回音频文件。
curl https://api.mumoo.cc/v1/audio/speech \
  -H "Authorization: Bearer $MUMOO_API_KEY" \
  -H "Idempotency-Key: my-app:voice-job-001" \
  -H "Content-Type: application/json" \
  -d '{"model":"speech-2.8-turbo","input":"你好，欢迎来到 MUMOO。","voice":"male-qn-qingse"}' \
  --output voice.mp3

异步任务：提交、查询、交付

1. 提交成功后保存完整响应、任务 ID、请求 ID 和应用自己的任务编号。
2. 使用同一账号和密钥查询原任务，建议从 3–5 秒间隔开始，逐步退避到 10–15 秒。读取接口不创建新的生成。
3. 任务成功后下载或保存结果；任务失败时查对应原单的退款状态。HTTP 请求成功与生成任务成功是两个状态。

核对原请求与费用

GET /v1/mumoo/external-requests/{request_id}/status 使用提交时返回的恢复编号，返回原请求编号、任务编号、任务状态和原生账单汇总。billing.state 分为待完成、已记录、退款处理中、已退款及需核对；消费、退款和净消耗分别给出。没有记录不会被说成免费，网络超时也不会被说成已退款。

status = client.outcome(result["receipt_id"])
print(status["data"]["billing"])
# 已保存的视频 task_id 只用于查询，下面的函数不会重新生成。
# client.poll("/v1/videos/" + task_id)

视频内容可通过 GET /v1/videos/{task_id}/content 携带密钥下载，支持字节范围读取。不要把密钥拼进可分享的 URL。结果地址可能过期，成功后及时保存；过期时先重新查询原任务。

重试与防重复提交

生成时建议始终附带 Idempotency-Key。普通原生客户端可省略此请求头，但每次调用将独立计费，不能自动去重。若策略中的 idempotency_required 为 true，则必须附带。使用 1–128 位字母、数字或 ._:-，推荐 UUID，并在客户端应用任务中保存。

• 同一密钥、同一编号和相同请求内容：返回已保存的原响应，或返回原请求待核对状态，不会再次进入生成与计费。
• 同一编号的请求内容、接口或影响输出的请求头不同：返回 409 idempotency_conflict。
• 成功响应通过 X-Mumoo-External-Request-Id 返回恢复编号，可调用 GET /v1/mumoo/external-requests/{request_id} 恢复原响应。
• 原响应损坏、请求中断、缓存容量不足或响应体超过 4 MiB 时，可能无法重放内容，但该编号仍保留防重记录。根据原请求或任务 ID 核对，不要换编号重提。
• 可重放的响应内容保留 24 小时，每个账号的外部响应缓存最多约 64 MiB；到期后返回 410 cached_result_expired。防重编号继续保留，查询原任务取回结果，不要重新生成。
• 加强保护的请求体上限为 16 MiB；大参考素材优先使用可访问的 URL。上传表单重试时，内容及 boundary 也必须保持一致。

限流使用独立的外部请求额度与并发预算，并按整个账号和全站限制后台任务数量。多建密钥不能绕过账号上限。当前数值和限流范围以 external-policy 为准；扩展到多个网关实例时必须使用共享限流存储。收到 429 时按 Retry-After 退避，同一任务仍使用原编号。

价格、预扣与结算

当前价格以模型与价格及账号实际权限为准。接口沿用已有模型价格、分组倍率和画布计费。可通过 GET /v1/mumoo/billing-info 查看与控制台同源的额度单位配置。

• 按 token、按次、按秒的模型分别按其规则计费；输入与输出、分辨率、时长和参考视频等选项可能改变费用。
• 预计消耗、提交时预扣与最终结算可能不同，核账时区分预扣、补差和退额，以原单最终净扣费为准。
• 明确失败按原有规则处理退额；网络超时不等于任务失败，也不等于已退款。
• 应用应在密钥层设置额度上限，并保存请求 ID、任务 ID 和自己的业务编号，便于与控制台使用记录核对。

目录中的 prices 已应用账号当前分组倍率。按次、按秒或每百万 token 对应 unit；输出和缓存价格单列。parameter_prices 给出分辨率、参考视频等选项的单价，不要与基础单价重复相乘。metered_cost 是按实际用量结算的工具：其 unit_price 为换算系数，参数单价已经换算；图像尺寸分档另见 image_size_rule。最终以原任务返回用量及账单为准。

一把密钥可允许同一分组中的多个模型；需要跨分组时使用控制台允许的自动分组，或为不同分组创建应用密钥。自动分组的各个候选价格会分别列出，不把不同路线混成一个固定价。用户账号所属分组、充值优惠和模型调用分组是不同设置。

出现错误时保留这些信息

x-request-id 是本次 HTTP 请求的追踪编号；X-Mumoo-Original-Request-Id 指向被恢复的原请求。报障时提供请求 ID、任务 ID、HTTP 状态和错误码，不要发送完整密钥。

兼容路由保留现有响应格式。加强保护新增的错误在 error.code 中给出稳定机器码。

运行状态

入口状态与生成记录分别显示。没有实际生成样本时显示“暂无样本”，历史成功率不代表服务方下一次请求一定成功。

型号维护、支持范围及接口变更会在当前文档和网关公告中说明。接入前查看最新模型目录，避免依赖已下架型号。