Rihpig

Posted on Oct 15 Originally published at apidog.com

Muse Wonder API 사용 방법

Muse Wonder API는 https://api.meta.ai/v1에서 muse-wonder-1.0 모델을 제공하는 Meta의 Model API입니다. Responses API, Chat Completions, Anthropic 호환 Messages 엔드포인트를 지원하며, dev.meta.ai에서 발급한 bearer 키로 인증합니다. 입력은 100만 토큰당 $4, 출력은 100만 토큰당 $20이며, 컨텍스트 창은 100만 토큰입니다. 추론 노력은 minimal부터 max까지 설정할 수 있고, 대부분의 OpenAI SDK는 베이스 URL만 바꾸면 사용할 수 있습니다.

지금 Apidog 사용해 보기

이 가이드는 API 키 발급부터 동작하는 에이전트 루프까지 다룹니다. 첫 요청, 엔드포인트 선택, 추론 제어, 멀티턴 상태, 도구 호출, 스트리밍, 백그라운드 실행, 비용 파악에 필요한 사용량 필드를 살펴봅니다. 모든 요청은 Apidog에서도 설정할 수 있어, 팀원들이 API 키를 공유하지 않고 같은 모델을 테스트할 수 있습니다. 모델 자체와 평가 점수는 먼저 Muse Wonder 설명 글을 참고하세요.

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`
100만 토큰당 가격	입력 $4, 출력 $20, 캐시 입력 $0.20
컨텍스트 창	1,048,576 토큰, 롱 컨텍스트 추가 요금 없음
추론 노력	`minimal`, `low`, `medium`, `high`, `xhigh`, `max`
속도 제한	팀당 모델당 분당 3,000 요청 및 400만 토큰
웹 검색 도구	토큰 비용 외에 1,000 쿼리당 $2.50

더 큰 모델인 Muse Wonder Full은 API로 제공되지 않습니다. Muse Code의 Power 및 Maximum 요금제에서만 사용할 수 있으며, Wonder의 추론 노력을 max로 설정해도 Full 모델로 바뀌지 않습니다.

1단계: 키 발급받고 첫 호출 만들기

Model API 대시보드의 API keys에서 키를 생성하고 MODEL_API_KEY 환경 변수로 저장하세요. 그다음 Responses API를 호출합니다.

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 Python SDK에서는 베이스 URL과 API 키만 지정하면 됩니다.

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)

응답에는 텍스트와 usage 블록이 포함됩니다. 모든 호출에서 이 블록을 확인하세요. output_tokens_details.reasoning_tokens는 출력 예산 중 추론에 사용된 토큰 수를 보여주고, input_tokens_details.cached_tokens는 캐시 요율로 과금된 입력 토큰 수를 나타냅니다.

2단계: 엔드포인트 선택하기

Meta 퀵스타트는 Responses API를 사용합니다. 여러 단계로 이루어진 작업이라면 Responses가 기본 선택입니다. Responses는 턴 간 추론을 유지하고 대화 기록을 관리할 수 있습니다. Chat Completions은 이미 OpenAI SDK 형식으로 작성된 코드를 위해 사용합니다. https://api.meta.ai/v1/messages의 Messages 엔드포인트는 Anthropic 형식 요청을 받으며, 이 경로를 통해 Claude Code가 Muse Wonder에서 실행됩니다.

필요 사항	사용할 API
새 에이전트, 도구 루프, 긴 세션	Responses
기존 OpenAI 형식 코드, 단일 턴	Chat Completions
Claude Code 또는 다른 Anthropic 형식 하네스	Messages
추론 요약	Responses 전용

세 가지 형식은 매개변수 이름이 다릅니다. 추론 노력은 Responses에서 reasoning.effort이고, Chat Completions에서는 최상위 reasoning_effort입니다. 출력 상한은 각각 max_output_tokens와 max_tokens입니다. Responses의 구조화 출력은 response_format이 아니라 text.format을 사용합니다.

3단계: 추론 노력 설정하기

Muse Wonder는 항상 추론합니다. none은 HTTP 400을 반환합니다. 허용되는 값은 minimal, low, medium, high, xhigh, max이며, 매개변수를 생략하면 모델이 수준을 선택합니다. 추론 토큰은 $20 출력 요율로 과금되고 출력 상한에 포함되므로, 허용 가능한 결과를 만드는 가장 낮은 수준을 사용하는 것이 비용 면에서 유리합니다.

두 가지 규칙을 권장합니다.

높은 추론 노력을 사용할 때는 max_output_tokens를 넉넉하게 설정하세요. max에서는 추론이 출력의 큰 부분을 차지할 수 있으므로, 상한이 낮으면 최종 답변이 잘릴 수 있습니다.
요청 유형별로 reasoning_tokens를 기록하세요. 벤치마크가 아니라 실제 트래픽에서 각 추론 수준의 비용을 확인해야 기본값을 합리적으로 정할 수 있습니다. 이 모델을 52점으로 평가한 Artificial Analysis 실행은 max 노력과 작업당 약 54,000 출력 토큰을 사용했습니다.

Responses API에서는 reasoning.summary를 auto, concise, detailed로 설정해 추론 요약을 요청할 수 있습니다. 요약은 보장되지 않으며 빈 배열로 반환될 수 있습니다. 원시 추론은 반환되지 않습니다.

4단계: 턴 간 상태 유지하기

Responses API는 두 가지 상태 유지 방식을 제공하며, 두 방식은 결합할 수 없습니다.

상태 비저장 암호화 재생은 Meta가 권장하는 방식입니다. store: false와 include: ["reasoning.encrypted_content"]를 보내고, 응답이 반환한 reasoning 항목을 저장한 뒤, 다음 요청에 encrypted_content와 summary 필드를 함께 다시 전달하세요. 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.",
)

5단계: 도구, 구조화 출력, 웹 검색 사용하기

함수 도구는 Responses와 Chat Completions에서 OpenAI 형식을 따릅니다. JSON Schema로 도구를 정의하고, 모델이 반환한 function_call 항목을 실행한 뒤, function_call_output 항목을 다시 보내세요. Muse Wonder는 도구를 병렬로 호출하고, 실패한 도구 호출에서 회복하도록 학습되었습니다. 이 특성은 Meta 출시 글에서 Active Focus라고 부르는 기능 중 하나입니다.

코드가 파싱할 수 있는 응답이 필요하다면 Responses에서 text.format을 JSON Schema로 설정하세요. 최신 정보가 필요하다면 tools=[{"type": "web_search"}]로 Meta의 호스팅 검색을 추가할 수 있습니다. 웹 검색은 토큰 비용 외에 1,000 쿼리당 $2.50으로 과금됩니다. 다른 모델의 도구 호출을 이미 테스트 중이라면, Apidog의 에이전트 도구 호출 하네스를 같은 방식으로 사용할 수 있습니다. 요청 형식은 OpenAI와 동일합니다.

6단계: 스트리밍 또는 백그라운드 실행하기

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

실패는 response.failed로 끝납니다. 추론 요약을 요청한 경우에는 response.reasoning_summary_text.delta 이벤트로 도착합니다.

긴 작업에는 background: true를 사용하세요. API는 "status": "queued"로 응답합니다. 이후 GET https://api.meta.ai/v1/responses/{id}?stream=true에서 수명 주기 이벤트를 폴링하거나 스트리밍할 수 있습니다. Background는 POST 요청의 stream: true와 결합할 수 없습니다. 요청 본문은 1 MiB로 제한되며, 팀당 분당 600건의 새 백그라운드 제출이라는 별도 한도가 있습니다. 작업은 POST https://api.meta.ai/v1/responses/{id}/cancel로 취소할 수 있습니다.

7단계: 반복되는 내용 캐시하기

캐시 입력은 100만 토큰당 $0.20입니다. $4 입력 요율과 비교하면 95% 할인입니다. Meta는 캐시 사용량을 usage.input_tokens_details.cached_tokens으로 보고합니다.

캐시 혜택을 극대화하려면 시스템 지시, 도구 정의, 참조 문서처럼 안정적인 자료를 프롬프트 앞부분에 두고, 요청마다 바뀌는 내용은 뒤에 두세요. 프롬프트 접두사를 설계하는 방법은 프롬프트 캐싱 가이드에서 자세히 다룹니다. 캐시 쓰기 비용도 주의해야 합니다. Artificial Analysis 실행에서는 작업당 $4.52 중 $1.92가 캐시 쓰기였고, 이는 캐시 히트 비용인 $1.44보다 많았습니다.

Apidog에서 Muse Wonder API 테스트하기

공유 Apidog 프로젝트는 API 키를 채팅 스레드 밖에 두고, 모든 팀원에게 같은 요청을 제공합니다.

환경을 만드세요. 이름은 Meta Model API로 지정하고, base_url을 https://api.meta.ai/v1로 설정하세요. MODEL_API_KEY는 비밀 변수로 저장하세요. 비밀 값은 UI에서 마스킹되며 내보내지지 않습니다.
세 개의 요청을 추가하세요. Responses, Chat Completions, Messages 엔드포인트마다 하나씩 만들고, 각 요청에 Authorization: Bearer {{MODEL_API_KEY}}를 설정하세요. Responses 요청을 low, medium, max 추론 노력용으로 복제하면 비용을 나란히 비교할 수 있습니다.
사용량을 검증하세요. $.usage.output_tokens_details.reasoning_tokens와 $.usage.input_tokens_details.cached_tokens에 JSONPath 어서션을 추가하세요. 캐시 히트를 기대한 요청에서 cached-tokens 값이 0이면 프롬프트 접두사에 문제가 있다는 뜻입니다. 프로덕션 배포 전에 이런 문제를 발견할 수 있습니다.
429 응답을 목업하세요. Meta 문서는 약 500 ms에서 시작하는 지터를 포함한 지수 백오프를 사용하고 Retry-After 헤더를 존중하라고 안내합니다. 해당 헤더와 함께 429를 반환하는 Apidog 목업에 클라이언트를 연결해, 팀 단위 분당 3,000 요청 한도를 공유하기 전에 재시도 로직을 검증하세요.
CI에서 실행하세요. Apidog CLI를 사용하면 모델 동작이나 가격이 변경될 때 고객 환경이 아니라 파이프라인에서 실패가 발생합니다.

Apidog를 다운로드하고 위 예제로 세 가지 엔드포인트를 바로 설정하세요.

자주 묻는 질문

Muse Wonder API에 무료 사용권이 있나요?

없습니다. 최소 금액 없이 토큰별로 과금되므로 소규모 테스트 호출은 몇 센트 수준일 수 있지만, 무료 크레딧은 제공되지 않습니다. 가장 저렴하게 접근하는 방법은 무료 접근 가이드를 참고하세요.

내 API 데이터가 학습에 사용되나요?

API의 Standard 모드에서는 사용되지 않습니다. Muse Code 구독은 기본적으로 데이터를 학습에 사용하는 Contributor 모드입니다. 이 설정은 API가 아니라 Muse Code에 있습니다.

API로 Muse Wonder Full을 사용할 수 있나요?

불가능합니다. Muse Wonder Full에는 API 호출용 모델 ID와 토큰별 가격이 없습니다. Muse Code Power 및 Maximum 구독자만 선택할 수 있습니다.

속도 제한은 무엇이며 늘릴 수 있나요?

모델당 분당 3,000 요청과 400만 토큰이며, 팀의 모든 키를 합산해 계산됩니다. Meta 가격 페이지에는 별도 등급이나 증액 절차가 없습니다. 한도 내에서 운영하는 방법은 속도 제한 글에서 다룹니다.

다음 단계

제품의 실제 작업 하나를 선택해 위 세 가지 호출을 low, medium, max 추론 노력으로 실행하세요. 기본값을 정하기 전에 reasoning_tokens를 비교하면 비용과 품질의 균형을 데이터로 판단할 수 있습니다. 청구서는 $4라는 입력 단가 표제가 아니라 실제 사용 토큰 수를 따릅니다.

DEV Community

Muse Wonder API 사용 방법

Muse Wonder API 사용 방법

Muse Wonder API 한눈에 보기

1단계: 키 발급받고 첫 호출 만들기

2단계: 엔드포인트 선택하기

3단계: 추론 노력 설정하기

4단계: 턴 간 상태 유지하기

5단계: 도구, 구조화 출력, 웹 검색 사용하기

6단계: 스트리밍 또는 백그라운드 실행하기

7단계: 반복되는 내용 캐시하기

Apidog에서 Muse Wonder API 테스트하기

자주 묻는 질문

Muse Wonder API에 무료 사용권이 있나요?

내 API 데이터가 학습에 사용되나요?

API로 Muse Wonder Full을 사용할 수 있나요?

속도 제한은 무엇이며 늘릴 수 있나요?

다음 단계

Top comments (0)