Como usar a API do Muse Wonder?

A API do Muse Wonder é a Model API da Meta que serve o muse-wonder-1.0 em https://api.meta.ai/v1, com três formatos de requisição: a API de Responses, o Chat Completions e um endpoint de Messages compatível com Anthropic. Você se autentica com uma chave Bearer [REDACTED] dev.meta.ai, paga $4 por milhão de tokens de entrada e $20 por milhão de saída, e recebe uma janela de contexto de 1 milhão de tokens com esforço de raciocínio de minimal a max. Qualquer SDK da OpenAI funciona depois que você muda a URL base.

Experimente o Apidog hoje

Este guia leva você da chave a um loop agêntico funcional: a primeira requisição, a escolha do endpoint, o controle do raciocínio, o estado entre turnos, as ferramentas, o streaming, as execuções em segundo plano e os campos de uso que mostram quanto custou cada chamada. Cada requisição também está configurada no Apidog para que o seu time possa testar o modelo sem passar a chave adiante. Para saber o que é o modelo e como ele pontua, comece pelo explicador sobre o Muse Wonder.

A API do Muse Wonder em resumo

	Valor
URL base	https://api.meta.ai/v1
ID do modelo	muse-wonder-1.0
Autenticação	Authorization: Bearer $MODEL_API_KEY
Endpoints	POST /v1/responses, POST /v1/chat/completions, POST /v1/messages
Preço por 1 milhão de tokens	$4 de entrada, $20 de saída, $0.20 de entrada em cache
Janela de contexto	1.048.576 tokens, sem acréscimo por contexto longo
Esforço de raciocínio	minimal, low, medium, high, xhigh, max
Limites de taxa	3.000 requisições e 4 milhões de tokens por minuto, por equipe e por modelo
Ferramenta de busca na web	$2.50 por 1.000 consultas, além dos tokens

O Muse Wonder Full, o modelo maior, não está na API. Ele só está disponível dentro do Muse Code, nos planos Power e Maximum. Definir o esforço como max no Wonder não o transforma no Full.

Etapa 1: obtenha uma chave e faça a primeira chamada

Crie uma chave no painel da Model API, em API keys, e armazene-a como MODEL_API_KEY. Depois:

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
  }'

Com o SDK da OpenAI, mude duas linhas:

from openai import OpenAI
import os

client = OpenAI(base_url="https://api.meta.ai/v1", [REDACTED CREDENTIAL]

resp = client.responses.create(
    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,
)
print(resp.output_text)
print(resp.usage)

A resposta traz o texto mais um bloco usage. Verifique-o em cada chamada: output_tokens_details.reasoning_tokens informa quanto do orçamento de saída foi para o raciocínio, e input_tokens_details.cached_tokens informa quanta entrada foi cobrada pela tarifa de cache.

Etapa 2: escolha um endpoint

O quickstart da Meta usa a API de Responses, e essa é a escolha padrão certa para qualquer coisa de vários passos. Ela preserva o raciocínio entre turnos e pode gerenciar o histórico da conversa para você. O Chat Completions existe para o código que você já tem contra um SDK da OpenAI. O endpoint de Messages em https://api.meta.ai/v1/messages aceita requisições em formato Anthropic, que é como o Claude Code roda sobre o Muse Wonder.

Necessidade	Use
Agente novo, loops de ferramentas, sessões longas	Responses
Código existente no estilo OpenAI, turnos únicos	Chat Completions
Claude Code ou outro harness em formato Anthropic	Messages
Resumos de raciocínio	Somente Responses

Os três formatos diferem nos nomes dos parâmetros. O esforço de raciocínio é reasoning.effort no Responses e um reasoning_effort no nível superior no Chat Completions. Os tetos de saída são max_output_tokens e max_tokens, respectivamente. A saída estruturada no Responses usa text.format, não response_format.

Etapa 3: defina o esforço de raciocínio

O Muse Wonder sempre raciocina. none retorna HTTP 400. Os níveis aceitos são minimal, low, medium, high, xhigh e max, e se você omite o parâmetro, o modelo escolhe o próprio nível. O conselho da Meta é o de sempre: use o nível mais baixo que entregue resultados aceitáveis, porque os tokens de raciocínio são cobrados pela tarifa de saída de $20 e contam para o seu teto de saída.

Daí decorrem duas regras práticas. Primeira, defina max_output_tokens com folga em esforços altos; em max, o raciocínio é uma fatia grande da saída, e um teto apertado trunca a resposta. Segunda, registre reasoning_tokens por tipo de requisição para ver quanto cada nível de esforço custa no seu tráfego, e não em um benchmark. As execuções da Artificial Analysis que pontuaram o modelo em 52 usaram esforço max e cerca de 54.000 tokens de saída por tarefa.

Na API de Responses você pode pedir um resumo do raciocínio definindo reasoning.summary como auto, concise ou detailed. Os resumos não são garantidos; o array pode voltar vazio. O raciocínio bruto nunca é retornado.

Etapa 4: carregue o estado entre turnos

A API de Responses oferece dois modos, e eles não podem ser combinados.

Replay criptografado sem estado é a recomendação da Meta. Envie store: false e include: ["reasoning.encrypted_content"], guarde os itens reasoning que a resposta retorna e passe-os de volta no próximo turno com o encrypted_content deles e um campo summary (um array vazio serve). O raciocínio do modelo sobrevive ao turno sem a Meta armazenar nada.

Histórico gerenciado pelo servidor é mais simples: passe previous_response_id e envie apenas a nova entrada. Note que instructions não é carregado adiante, então reenvie suas instruções de sistema em cada requisição.

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

Etapa 5: ferramentas, saída estruturada e busca na web

As function tools seguem o formato da OpenAI no Responses e no Chat Completions. O Muse Wonder chama ferramentas em paralelo e é treinado para se recuperar de chamadas que falham, que é uma das coisas que o post de lançamento da Meta quer dizer com Active Focus. Defina as ferramentas com um schema JSON, execute os itens function_call que o modelo retorna e devolva itens function_call_output.

Para uma resposta que o seu código consiga interpretar, defina text.format com um schema JSON no Responses. Para informações atuais, adicione a busca hospedada da Meta com tools=[{"type": "web_search"}]; ela é cobrada a $2.50 por 1.000 consultas, além dos tokens. Se você já testa chamadas de ferramentas para outros modelos, o harness de testes de tool calls para agentes do Apidog funciona aqui sem alterações: o formato da requisição é o mesmo da OpenAI.

Etapa 6: faça streaming ou execute em segundo plano

Defina stream: true e consuma o fluxo de eventos: response.created, response.output_item.added, response.output_text.delta, response.function_call_arguments.delta e response.completed. Uma falha termina com response.failed. Os resumos de raciocínio chegam como response.reasoning_summary_text.delta quando solicitados.

Para trabalhos longos, envie background: true. A API confirma o recebimento com "status": "queued", e você faz polling ou consome os eventos do ciclo de vida em GET /v1/responses/{id}?stream=true. O background não pode ser combinado com stream: true no POST, o corpo da requisição tem limite de 1 MiB e há um limite separado de 600 novos envios em segundo plano por minuto por equipe. Cancele com POST /v1/responses/{id}/cancel.

Etapa 7: faça cache do que se repete

A entrada em cache custa $0.20 por milhão, 95% de desconto sobre a tarifa de $4, e a Meta a reporta em usage.input_tokens_details.cached_tokens. O padrão que garante o desconto é o mesmo dos outros provedores: coloque o material estável (instruções de sistema, definições de ferramentas, documentos de referência) primeiro e o conteúdo por requisição por último. O guia de prompt caching cobre o design do prefixo. Fique de olho também na gravação do cache: na execução da Artificial Analysis, $1.92 dos $4.52 por tarefa do Wonder foram gravações em cache, mais do que os $1.44 em acertos de cache.

Teste a API do Muse Wonder no Apidog

Um projeto compartilhado do Apidog mantém a chave longe dos threads de chat e dá a todo mundo as mesmas requisições.

1. Crie um environment chamado Meta Model API com base_url de https://api.meta.ai/v1 e MODEL_API_KEY como variável secreta. Valores secretos ficam mascarados na interface e nunca são exportados.
2. Adicione três requisições, uma por endpoint, cada uma com Authorization: Bearer {{MODEL_API_KEY}}. Duplique a requisição de Responses com esforço low, medium e max para comparar custos lado a lado.
3. Faça asserções sobre o uso. Adicione asserções JSONPath em $.usage.output_tokens_details.reasoning_tokens e $.usage.input_tokens_details.cached_tokens. Um valor de cached-tokens igual a zero numa requisição em que você esperava acertar o cache é um bug de prefixo, detectado antes de chegar à produção.
4. Sirva um mock do 429. A documentação da Meta manda recuar exponencialmente com jitter a partir de cerca de 500 ms e respeitar o Retry-After. Aponte o seu cliente para um mock do Apidog que retorna 429 com esse header e prove a lógica de retry antes de dividir com o resto do time um limite de 3.000 requisições por minuto.
5. Rode no CI com a CLI do Apidog para que uma mudança de modelo ou de preço quebre um pipeline, e não um cliente.

Baixe o Apidog e importe os três endpoints dos exemplos de requisição acima.

Perguntas frequentes

A API do Muse Wonder tem um nível gratuito? Não. A cobrança é por token, sem mínimo, então um punhado de chamadas de teste custa centavos, mas não há créditos gratuitos. O guia de acesso gratuito cobre as rotas mais baratas.

Meus dados de API são usados para treinamento? Não no modo Standard da API. As assinaturas do Muse Code usam por padrão o modo Contributor, que usa os seus dados; essa configuração fica no Muse Code, não na API.

Posso usar o Muse Wonder Full pela API? Não. Ele não tem um ID de modelo que possa ser chamado nem preço por token. Somente assinantes do Muse Code Power e Maximum podem selecioná-lo.

Quais são os limites de taxa e dá para aumentá-los? 3.000 requisições e 4 milhões de tokens por minuto por modelo, contabilizados entre todas as chaves do seu time. A página de preços da Meta não lista tiers nem um processo para aumentos. O post sobre limites de taxa mostra como ficar abaixo deles.

Próximo passo

Faça as três chamadas acima com esforço low, medium e max em uma tarefa real do seu produto e compare reasoning_tokens antes de escolher um padrão. Esse número, e não o titular dos $4, é o que a sua fatura vai acompanhar.