Cookbook

You're Claude Code, working in my repository.

Task
Pick the cookbook recipe that fits this project best and tell me which one and why in two sentences. Then build its core call into this project: one function that sends the recipe's key request to Meta Model API and returns the field that recipe reads from the reply. Read that recipe's own page as Markdown (https://dev.meta.ai/docs/cookbook/<recipe>.md) before you write code.

Read this first
Meta's docs page "Cookbook" as Markdown: https://dev.meta.ai/docs/cookbook.md
It's the source of truth for request and response shapes. The same page for people: https://dev.meta.ai/docs/cookbook

Setup
- Base URL: https://api.meta.ai/v1
- Auth: send Authorization: Bearer $MODEL_API_KEY, reading MODEL_API_KEY from the environment. Never hard-code, print or commit the key.
- Model: muse-spark-1.3-contributor (Contributor mode: Meta may use what you send to train future models; drop -contributor for Standard mode)
- Python: the OpenAI SDK (pip install openai) with base_url="https://api.meta.ai/v1" and api_key=os.environ["MODEL_API_KEY"] works, or plain requests.

Facts to get right
- Text recipes use Chat Completions (POST /v1/chat/completions) or Responses (POST /v1/responses); web search and reasoning items are Responses only.
- Models: muse-spark-1.3-contributor for text (drop -contributor for Standard mode), sam-3.1 for segmentation, muse-voice-transcribe-1.0 on POST /v1/asr/transcribe (multipart).
- muse-image-1.0 ($0.01 an image): its recipes call it on Responses; POST /v1/images/generations and /v1/images/edits take it too.
- Muse Code recipes run in the muse CLI (curl -fsSL https://dev.meta.ai/install.sh | sh) and open-weight recipes on your own hardware: neither is a Model API call.
- The OpenAI SDK doesn't read MODEL_API_KEY: pass it as the api key.

Starter code (Python)
import os

from openai import OpenAI

client = OpenAI(base_url="https://api.meta.ai/v1", api_key=os.environ["MODEL_API_KEY"])

# The quickstart recipe's core call: a model and a messages array.
response = client.chat.completions.create(
    model="muse-spark-1.3-contributor",
    messages=[{"role": "user", "content": "In two sentences, what is the Meta Model API?"}],
)
print(response.choices[0].message.content)
print("finish_reason:", response.choices[0].finish_reason)
print("usage:", response.usage)

Done when
- You named the recipe and why it fits.
- Running the new function once makes a real call and prints the field the recipe's page says to read.
- The key comes from MODEL_API_KEY and never appears in code, logs or commits.
- API errors (4xx, 429) surface their message instead of failing silently.

Recipes for building with Muse models, from your first API call to complete solutions.

Meta Model API#

Learn how to build on Meta Model API. Each recipe solves a specific problem with ready code samples you can copy to follow along. Start with API fundamentals to nail the primitives of prompt and response usage with Muse models, then explore how to use other models like Muse Image, Muse Voice Transcribe and Segment Anything Model.

View on GitHub (opens in a new tab)

API fundamentals#

Validate one building block at a time and walk away with a starter you can extend.

• Quickstart: chat completionsPoint the OpenAI SDK at a new base URL and make your first Muse Spark call.
• Streaming responsesStream tokens as they generate and read usage in the final chunk.
• Tool and function callingDetect a tool call, execute it, and feed the result back into the loop.
• Structured outputReturn JSON that matches your schema and parses on the first try.
• Prompt cachingReuse a stable prompt prefix and measure cached tokens.
• Reasoning and thinking tokensSet reasoning effort and replay reasoning across turns.
• Vision inputSend images by URL or base64 and get structured analysis back.
• Long contextPack repo-scale context into a single context window.
• Error handling and retryBack off with jitter and skip retries on client errors.
• Search groundingGround answers in live web search with inline citations.

Agent patterns#

Turn a model into an agent. These loops handle planning, self-correction, and staying coherent across long runs.

• Basic agent loopWire up the core perceive-decide-act loop.
• Interleaved reasoning and tool useInterleave reasoning with tool calls in a single turn.
• Multi-turn context managementKeep context under control across a long agent run.
• Search-and-replace editsMake exact-match file edits that stay reviewable.
• Alert fatigue copilotPull grounded patterns from noisy alerts, then probe, chat, and self-assess with strict JSON.

Use cases#

Build end-to-end: multimodal perception, orchestration, and complete apps you can adapt.

• Chart analysisRead charts and extract structured data from images.
• Error screenshot fixDiagnose a bug from a screenshot and ship the fix.
• Smart glasses with OpenClawLook, ask out loud, and hear the answer, hands-free on Ray-Ban Meta glasses.
• Generating slidesGenerate a slide deck from a prompt or source content.
• Browser-verified web designBuild a website with a coding agent that checks its own work in a real browser.
• Iterative game devBuild a browser game end-to-end with a coding agent, verified in a real browser.
• Sandboxed executionExecute model-generated code in a sandbox.
• Multi-agent orchestrationOrchestrate a team of specialists that coordinate through a shared Kanban board.
• One-shot game devBuild a complete 3D browser game in one pass, one structured prompt, no iteration loop.
• Perception groundingPin interactive dots at object pixel locations and generate a self-contained HTML overlay.
• GitHub agentRun an autonomous GitHub Actions bot for triage, PR review, and bug-fix PRs on OpenCode and Muse Spark.
• Computer useControl a desktop from screenshots with a computer-use agent.
• Computer use on macOSDrive a real Mac from screenshots with native mouse and keyboard events.
• Local agent that asks firstRun Muse Glimmer locally and escalate to Muse Spark only after you approve the text the tool is about to send.

Building with Muse Code#

Build durable, auditable agents with Muse Code, the harness building blocks for safety, recovery, and orchestration.

• Audit and resume agent sessionsReplay any session exactly as it ran from an append-only event log, show who authorized each action, then kill the run mid-task and resume with no duplicate side effects.
• Deterministic replay in CITurn recorded events into a golden fixture and replay its model-context projection as a merge-blocking CI check.
• Staged approvalsSplit a compound shell command into stages so safe ones auto-resolve while risky ones hold for review.
• Contained executionRun every command in an OS sandbox that refuses to proceed unless containment is proven live.
• Immutable guardrailsThe agent can't rewrite its own rules: guardrail edits stop for review and a shell write to the same path fails read-only at the sandbox.
• Subagent fanoutFan one job out to parallel subagents, each in its own isolated git worktree.
• Goal trackingPin an objective once and the harness audits the work against acceptance checks before the goal can close.
• Bundled skillsDrive the built-in /plan, /grilling, /grill-with-docs, and /taste skills to plan, pressure-test, and build.
• Loop and cronSchedule recurring or one-time agent work in natural language, then view, change, or cancel it from the same chat.
• Side chatsBranch off the main thread for a side conversation that never enters the main history.

Muse Image#

Use Muse Image to generate, edit, or combine images. Choose a recipe based on whether you need web grounding, consistency across a series, or multi-turn editing.

• Generate, edit, and compose imagesGenerate an image, refine it across turns, or combine it with new reference images.
• Ground image generation with web searchUse web references when an image should reflect current products, places, or styles. Verify factual details independently.
• Keep an image series consistentUse reference images to improve character, style, and setting consistency across a series. Compare each output with the references.
• Edit image details across turnsEdit one part of a photo, then refine the result across turns. Check that unchanged areas still match the source.

Muse Voice Transcribe#

Use Muse Voice Transcribe to turn speech into text, streaming over a WebSocket while the speaker is still talking, or in one HTTP request for a recording you already have. The model handles punctuation, speech-boundary detection, and speaker attribution itself.

• Speech to textTranscribe a recording or a live microphone over the streaming WebSocket, get speaker-attributed turns with diarization, or post a whole recording in one HTTP request.
• Control Apple Chess with voiceTurn exact spoken chess moves into locally validated Apple Chess actions with a passive HUD, calibrated grid, dry-run mode, and fail-closed native input.

Segment Anything Model#

Use Segment Anything Model to find and cut out objects in images and video from a short noun phrase. SAM 3.1 returns a box and a pixel mask for every match, and holds each object's identity across a whole clip, so a recipe can track and composite without per-frame bookkeeping.

• SAM API basicsSegment an image or an uploaded video in Python or TypeScript, streaming the response and parsing it with the official meta-sam parsers.
• Video to animated stickersTrack an animal through a clip, cut the background from its longest-lived track, and export transparent animated stickers.
• Multi-speaker headlocked captionsMatch diarized voices to SAM-tracked people, preview collision-aware speech bubbles, and download the captioned video.

Open-weight models#

Run Muse models yourself with the open weights, on hardware you control.

View on GitHub (opens in a new tab)

Run locally#

Serve a Muse open-weight model on your own machines, step by step.

• Muse Spark Open on MacRun Muse Spark Open on two or four Mac Studios.

Post-training#

Fine-tune a Muse open-weight model on your own data, step by step.

• RL with TorchTitanGRPO with the DAPO loss on a task you plug in, starting from DAPO-Math.
• SFT with TorchTitanFull-parameter SFT on your own text, image, and audio conversations.

Mirrored from dev.meta.ai/docs/cookbook (synced Oct 30, 2026). Text and examples © Meta. Live demos run on Muse Muse's key.