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

Muse Wonder 是 Meta 推出的 Model API 模型，通过 https://api.meta.ai/v1 提供 muse-wonder-1.0 服务。它同时支持三种请求格式：Responses API、Chat Completions，以及兼容 Anthropic 格式的 Messages 端点。认证方式是 Bearer 密钥，输入定价为每百万 token 4 美元，输出为 20 美元，缓存输入仅 0.20 美元，上下文窗口达到 1,048,576 token，并且不因长上下文额外加价。

Muse Wonder API 请求示意

对于熟悉 OpenAI SDK 的开发者，只需修改两行代码——替换 base_url 与 api_key——即可迁移到 Muse Wonder。本文从密钥获取一路讲到可运行的 agent 循环，涵盖端点选择、推理强度控制、跨轮次状态管理、工具调用、流式输出、后台执行以及用量字段解读。

Muse Wonder API 核心参数

在动手写第一行代码之前，先看清这张规格表。

项目	值
基础 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。

第一步：获取密钥并发起首次调用

在 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 和密钥两处，其余调用方式完全一致。响应中除了文本，还会返回一个 usage 块。养成每次调用都检查它的习惯：output_tokens_details.reasoning_tokens 告诉你输出预算中有多少花在了推理上，input_tokens_details.cached_tokens 则显示有多少输入享受了缓存费率。

第二步：选择合适的端点

Meta 的快速入门使用 Responses API，这也是多步骤任务的默认正确选择——它在轮次之间保留推理过程，并能替你管理对话历史。Chat Completions 则面向已经在使用 OpenAI SDK 的存量代码。Messages 端点接受 Anthropic 格式请求，Claude Code 正是通过这一端点运行在 Muse Wonder 之上。

需求	推荐端点
新 agent、工具循环、长会话	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。

什么是 Responses API？ 这是 OpenAI 于 2025 年推出、用于取代 Chat Completions 的新一代接口，把「对话」抽象为一系列有序的 item（消息、工具调用、推理项等），并原生支持服务端保存会话状态、后台执行和内置工具。Muse Wonder 的 Responses 端点基本对齐这一设计，因此 previous_response_id、reasoning.encrypted_content、tools 等字段都能直接沿用 OpenAI 的语义。对开发者来说，这意味着原本为 OpenAI Responses 写的代码只需替换 base_url 与密钥即可运行。

Messages 端点与 Anthropic 格式 是 Anthropic Claude API 的原生请求格式，结构上以 system 加 messages 数组为核心，工具调用通过 tool_use / tool_result 内容块表达，与 OpenAI 风格差异明显。Muse Wonder 提供兼容实现，使得 Claude Code 这类已经深度绑定 Anthropic 格式的客户端无需改造即可切换底层模型，这也是它在三类端点中存在的核心价值。

第三步：控制推理强度

Muse Wonder 始终进行推理，设为 none 会返回 HTTP 400。可接受的级别是 minimal、low、medium、high、xhigh 和 max；如果省略该参数，模型自行选择级别。Meta 的建议一如既往：使用能给出可接受结果的最低级别，因为推理 token 按 20 美元的输出费率计费，并且占用你的输出上限。

由此衍生出两条实用规则。其一，在高强度下给 max_output_tokens 留足余量；在 max 级别，推理占据输出的很大一部分，上限设得太紧会截断回答。其二，按请求类型记录 reasoning_tokens，了解每个强度级别在你自己的流量中花多少钱，而不是看基准测试。Artificial Analysis 将模型评为 52 分的那次运行使用了 max 强度，每项任务约 54,000 个输出 token。

在 Responses API 中，你可以通过把 reasoning.summary 设为 auto、concise 或 detailed 来请求推理摘要。摘要不保证返回，数组可能为空。原始推理内容永远不会返回。

推理 token 是现代「思考型」模型的内部独白，模型会先产生一段不直接展示给用户的中间推理，再输出最终答案。这段内容的计费方式与普通输出完全相同，因此在高强度设置下可能占据输出预算的绝大部分。基准测试机构在评测时往往使用最高强度，导致报告的成本数字远高于生产环境的实际水平。要估算真实成本，应当在自己的流量上按请求类型抽样记录 reasoning_tokens，再乘以对应费率。

reasoning.summary 请求的是模型对这段推理过程的可读摘要，而不是原始推理内容本身。原始思维链通常被视为敏感且可能含有噪音，多数厂商选择不返回；摘要则是二次生成的压缩版本，因此可能为空、措辞高度概括，不适合当作调试推理逻辑的依据。

第四步：在轮次之间传递状态

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.")

第五步：工具、结构化输出与联网搜索

Function tools 在 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 美元计费，另加 token 费用。

第六步：流式输出与后台执行

设置 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 上消费生命周期事件。后台模式不能在 POST 中与 stream: true 组合，请求体上限为 1 MiB，并且每团队每分钟有 600 次新后台提交的单独限制。用 POST /v1/responses/{id}/cancel 取消。

第七步：为重复内容做缓存

缓存输入每百万 token 仅 0.20 美元，相对 4 美元的标准费率便宜 95%，Meta 通过 usage.input_tokens_details.cached_tokens 报告命中情况。确保折扣的模式与其他提供商一致：把稳定内容（系统指令、工具定义、参考文档）放在前面，把每次请求变化的内容放在最后。同时留意缓存写入——在 Artificial Analysis 的那次运行中，Wonder 每任务 4.52 美元里有 1.92 美元是缓存写入，比 1.44 美元的缓存命中还多。

提示缓存的工作原理是：提供商对请求前缀做哈希，命中已缓存的前缀时按折扣价计费。因此前缀必须逐字节稳定——哪怕系统指令里改动一个字符，后续所有内容都会从缓存失效处重新计算。常见做法是把 system prompt、工具 JSON schema、检索到的固定文档放在最前，把用户问题和时间戳等易变内容放在最后。

缓存写入指的是首次把新前缀放入缓存的成本，通常按标准输入价或略高费率计费；缓存命中才是享受折扣的读取。对于前缀很长但复用次数不多的场景，写入成本可能高于节省下来的命中费用，这一点在按量计费的 API 中尤其需要实测验证。

在 Apidog 中测试 Muse Wonder API

一个共享的 Apidog 项目能让密钥远离聊天线程，并让所有人使用相同的请求配置。

创建环境，命名为 Meta Model API，设置 base_url 为 https://api.meta.ai/v1，把 MODEL_API_KEY 设为密钥变量，密钥值在界面中会被遮蔽，也不会被导出。
添加三个请求，每个端点一个，都带上 Authorization: Bearer {{MODEL_API_KEY}}。把 Responses 请求复制三份，分别使用 low、medium 和 max 强度，以便并排比较成本。
对用量做断言。在 $.usage.output_tokens_details.reasoning_tokens 和 $.usage.input_tokens_details.cached_tokens 上添加 JSONPath 断言。在你预期命中缓存的请求中出现 cached-tokens 为零，说明前缀设计有 bug，能在进入生产之前被捕获。
模拟 429。Meta 文档建议从约 500 毫秒开始进行带抖动的指数退避，并遵守 Retry-After。把客户端指向返回带该 header 的 429 的 Apidog mock，在与团队共享每分钟 3,000 次请求的限额之前先验证重试逻辑。
在 CI 中运行，通过 Apidog CLI，让模型或价格变更触发流水线失败，而不是让客户端崩溃。

常见问题

Muse Wonder API 有免费额度吗？ 没有。按 token 计费，无最低消费，所以少量测试调用只需几美分，但没有免费赠额。

API 数据会被用于训练吗？ 在 API 的 Standard 模式下不会。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 美元的头条价格——才是你的账单将跟踪的对象。