Muse Wonder API 使用指南：端点、成本与推理控制

Meta 推出的 Muse Wonder API 以 muse-wonder-1.0 模型为核心，通过 https://api.meta.ai/v1 提供服务，支持 Responses API、Chat Completions 和兼容 Anthropic 的 Messages 三种请求格式。定价为每百万输入 token 4 美元、输出 20 美元，上下文窗口高达 1,048,576 token，且长上下文不收取额外费用。推理力度可从 minimal 调到 max，任何 OpenAI SDK 只需更换 base URL 即可直接使用。

Muse Wonder API 核心参数一览

在动手写代码之前，先看清这张速查表。所有端点都通过 bearer key 鉴权，密钥在 dev.meta.ai 的 Model API 控制台创建。

项目	值
Base URL	https://api.meta.ai/v1
模型 ID	muse-wonder-1.0
鉴权	Authorization: Bearer $MODEL_API_KEY
端点	POST /v1/responses、POST /v1/chat/completions、POST /v1/messages
每百万 token 定价	输入 $4，输出 $20，缓存输入 $0.20
上下文窗口	1,048,576 token，无长上下文附加费
推理力度	minimal、low、medium、high、xhigh、max
速率限制	每团队每模型 3,000 请求/分钟、400 万 token/分钟
网页搜索工具	每 1,000 次查询 $2.50，另计 token 费用

需要特别留意的是，更大的 Muse Wonder Full 模型并不通过 API 提供，它仅内嵌于 Muse Code 的 Power 和 Maximum 订阅计划中。把 Wonder 的推理力度调到 max 也不会让它变成 Full。

什么是 Responses API？ 这是 OpenAI 于 2025 年推出的一种新端点，用于取代 Chat Completions 成为构建智能体应用的首选接口。它把会话状态、工具调用、结构化输出、后台运行、流式事件等能力统一到一套对象模型里，特点是所有事情都表示为 response 对象下的 item，跨轮次时可通过 previous_response_id 或回传 reasoning 项保留模型内部状态。相比 Chat Completions 的 messages 数组，Responses 能原生携带推理内容和工具调用轨迹，因此对多步任务更友好。Muse Wonder 把 Responses 作为官方推荐入口，正是因为其核心卖点——可控推理力度与跨轮次推理保持——只有在这个端点上才完整可用。

三步完成首次 API 调用

第一步：获取密钥并发出请求

在 Model API 仪表盘的 API keys 页面创建密钥并保存为 MODEL_API_KEY，然后即可用 cURL 发起请求：

curl https://api.meta.ai/v1/responses \
  -H "Authorization: Bearer $MODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-wonder-1.0",
    "input": "List three risks in a lease clause that lets the landlord enter without notice.",
    "reasoning": {"effort": "medium"},
    "max_output_tokens": 2048
  }'

使用 OpenAI SDK 时只需修改两行——将 base_url 指向 https://api.meta.ai/v1，模型名改为 muse-wonder-1.0。响应中会携带 usage 块，每次调用都应检查它：output_tokens_details.reasoning_tokens 告诉你输出预算中有多少花在了推理上，input_tokens_details.cached_tokens 则显示有多少输入享受了缓存价格。

第二步：选择合适的端点

Meta 官方入门指南推荐使用 Responses API，它是任何多步骤工作的正确默认选项，能够跨轮次保持推理状态，并可代为管理对话历史。Chat Completions 则为已有 OpenAI 风格代码而保留。Messages 端点接受 Anthropic 格式的请求，这正是让 Claude Code 跑在 Muse Wonder 之上的关键。

需求场景	推荐端点
新建智能体、工具循环、长会话	Responses
已有 OpenAI 风格代码、单轮任务	Chat Completions
Claude Code 或其他 Anthropic 框架	Messages
需要推理摘要	仅 Responses

三种格式的参数命名存在差异：推理力度在 Responses 中是 reasoning.effort，在 Chat Completions 中是顶层的 reasoning_effort；输出上限分别是 max_output_tokens 和 max_tokens；结构化输出在 Responses 中使用 text.format 而非 response_format。

第三步：调节推理力度

Muse Wonder 始终进行推理，传入 none 会返回 HTTP 400 错误。接受的值包括 minimal、low、medium、high、xhigh、max，省略参数时模型自行选择。Meta 的建议很直白：使用能给出可接受结果的最低级别，因为推理 token 按 20 美元的输出价格计费，且计入输出上限。

由此衍生出两条实践规则。其一，高推理力度下应把 max_output_tokens 设得宽裕些，在 max 级别时推理会占据输出的很大比例，过窄的上限会截断答案。其二，按请求类型记录 reasoning_tokens，看清每个推理级别在你自己工作负载上的真实成本，而非依赖某个基准测试。据 Artificial Analysis 的测试数据，该模型在 max 力度下平均每任务消耗约 54,000 个输出 token。

在 Responses 界面中，可将 reasoning.summary 设为 auto、concise 或 detailed 来请求推理摘要。摘要是非保证的，可能返回空数组，而原始推理内容永远不会返回。

推理 token 与思维链计费 指的是模型在给出最终答案之前，于内部生成的中间推理步骤。这类 token 不属于用户可见输出，但仍按输出价格计费，并占用 max_output_tokens 的额度。行业里常说的“思考预算”就是控制这部分。Muse Wonder 与 OpenAI o 系列、Anthropic 的 extended thinking 属于同一类做法：用一个离散的 effort 档位替代显式的 token 数，让模型自行伸缩推理长度。不同之处在于，有的模型允许关闭推理（如 OpenAI 的 reasoning_effort: none），而 Muse Wonder 强制始终推理，none 直接报 400。理解这一点对成本估算至关重要：即便答案只有几十个 token，一次 max 级别的调用也可能烧掉数万输出 token。

跨轮次保持状态的两种方式

Responses API 提供两种模式，二者不能混用。

无状态加密回放是 Meta 的推荐做法。发送 store: false 和 include: ["reasoning.encrypted_content"]，保留响应返回的 reasoning 项，在下一轮中连同 encrypted_content 和 summary 字段（空数组也够用）一起传回。模型的推理在轮次之间得以保留，而 Meta 不存储任何内容。

服务端托管历史更简单：传入 previous_response_id，只发送新输入。需要注意 instructions 不会跨轮次携带，每次请求都要重新发送系统指令。

first = client.responses.create(model="muse-wonder-1.0", input="Summarize this API's auth flow: ...", instructions="You are an API reviewer.")
second = client.responses.create(model="muse-wonder-1.0", previous_response_id=first.id, instructions="You are an API reviewer.", input="Now list the endpoints that need an OAuth scope.")

工具调用、结构化输出与网页搜索

函数工具在 Responses 和 Chat Completions 中遵循 OpenAI 格式。Muse Wonder 能并行调用工具，并经过失败工具调用的恢复训练——这正是 Meta 发布博客中 Active Focus 一词的部分含义。用 JSON schema 定义工具，执行模型返回的 function_call 项，再回传 function_call_output 项。

若想让代码解析响应，在 Responses 中将 text.format 设为 JSON schema。若需要实时信息，可通过 tools=[{"type": "web_search"}] 添加 Meta 托管的网页搜索，每 1,000 次查询额外计费 2.50 美元。如果你已经在测试其他模型的工具调用，现有的测试平台无需改动——请求格式与 OpenAI 相同。

流式输出与后台运行

设置 stream: true 后消费事件流：response.created、response.output_item.added、response.output_text.delta、response.function_call_arguments.delta，最后是 response.completed。失败以 response.failed 结束。请求后推理摘要会以 response.reasoning_summary_text.delta 形式到达。

对于长任务，发送 background: true。API 以 "status": "queued" 确认接收，你可以轮询或从 GET /v1/responses/{id}?stream=true 流式获取生命周期事件。background 与 stream: true 不能在同一个 POST 请求中并存，请求体上限为 1 MiB，后台任务另有每分钟 600 个新请求的独立限制。取消可通过 POST /v1/responses/{id}/cancel 完成。

缓存重复内容可省 95%

缓存输入每百万 token 仅需 0.20 美元，比 4 美元的标准输入价格便宜 95%，Meta 通过 usage.input_tokens_details.cached_tokens 报告这一数据。获利的模式与其他提供商一致：固定材料（系统指令、工具定义、参考文档）放前面，每个请求独有的内容放最后。

同时监控缓存的写入侧。据 Artificial Analysis 的测试，Wonder 每任务 4.52 美元成本中有 1.92 美元花在缓存写入上，超过了 1.44 美元的缓存命中。这意味着缓存策略的优化空间可能比想象中更大。

前缀缓存（prompt caching） 是各大模型 API 普遍采用的优化机制：如果两次请求的开头部分是逐字节相同的，服务端可以复用上一次已经计算过的 KV 缓存，从而跳过重复的 prefill 计算，只对新增部分计费。命中缓存的价格通常是标准输入价的 5% 到 10%，Muse Wonder 的 0.20 美元/百万 token 正处于这个区间。要命中缓存，前缀必须完全一致，包括系统提示、工具定义、示例的措辞与顺序，任何一处改动都会让缓存从该点之后全部失效。文中提到缓存写入成本高于命中，这是因为第一次写入需要以标准价计费，而缓存有存活时间（通常几分钟到一小时），过期后需要重新写入。所以缓存策略要围绕“稳定前缀 + 动态后缀”来设计，且尽量在缓存有效期内重复利用。

在 Apidog 中测试 Muse Wonder API

共享的 Apidog 项目能把密钥留在聊天窗口之外，让全队使用相同的请求。

1. 创建环境：命名为 Meta Model API，base_url 设为 https://api.meta.ai/v1，将 MODEL_API_KEY 作为秘密变量。秘密值在界面中被屏蔽且永不导出。
2. 添加三个请求：每个端点一个，都带上 Authorization: Bearer {{MODEL_API_KEY}}。为 Responses 请求分别设置 low、medium、max 力度，以并排比较成本。
3. 添加用量断言：对 $.usage.output_tokens_details.reasoning_tokens 和 $.usage.input_tokens_details.cached_tokens 添加 JSONPath 断言。预期缓存命中却得到零值时，表明前缀设计有问题，可以在进入生产前捕获。
4. 模拟 429 错误：Meta 文档建议从约 500ms 开始指数退避并加入 jitter，同时尊重 Retry-After 头。将客户端指向返回 429 及该头的 Apidog mock，在团队共享每分钟 3,000 请求限制之前验证重试逻辑。
5. 在 CI 中运行：通过 Apidog CLI 运行，让流水线在模型或价格变动时失败，而不是让客户端崩溃。

常见问题

Muse Wonder API 有免费层吗？ 没有。按 token 计费，无最低消费，少数几次试调用只需几分钱，但没有免费额度。

API 数据会被用于训练吗？ Standard 模式下的 API 不会。Muse Code 订阅默认使用 Contributor 模式，该模式确实会使用你的数据，但这一设置存在于 Muse Code 而非 API 中。

能通过 API 使用 Muse Wonder Full 吗？ 不能。它没有可调用的模型 ID，也没有每 token 价格。只有 Muse Code Power 和 Maximum 订阅者可以选择它。

速率限制是多少，能提升吗？ 每模型每分钟 3,000 请求和 400 万 token，按团队所有密钥合计计算。Meta 定价页面未列出层级或提升流程。

下一步

用产品中的真实任务运行 low、medium、max 三个力度的调用，在选定默认值之前比较 reasoning_tokens。那个数字，而不是 4 美元的标题价格，才是你要跟踪的账单依据。

背景补充

关于 Apidog 是本文用来演示 API 测试的协作工具，属于“API 设计 + 调试 + Mock + 自动化测试”一体的平台。它的核心价值在于把环境变量、密钥、请求定义、断言集中管理，团队成员共享同一套配置，避免把 MODEL_API_KEY 粘贴到聊天窗口或代码注释里。文中演示的五个步骤——建环境、加请求、加用量断言、模拟 429、接入 CI——基本覆盖了从本地试调到流水线监控的完整链路。Apidog CLI 让这些断言可以在持续集成中运行，一旦 Meta 调整模型版本或定价，流水线可以先于客户端感知并中断。如果你已经在用 Postman 或 Bruno，思路是相通的，区别主要在于团队协作和 Mock 服务的集成度。