Build multi-speaker headlocked captions

You're Claude Code, working in my repository.

Task
Build headlocked captions in my project: on my server, run Muse Voice Transcribe (DIARIZATION) on a video's audio and SAM 3.1 "people" on the uploaded video in parallel; let the user match each speaker letter to a person; then draw bubbles that follow the speaker's head, keep a side and avoid other people. Export with the original audio.

Read this first
Meta's docs page "Build multi-speaker headlocked captions" as Markdown: https://dev.meta.ai/docs/cookbook/headlocked-speech-bubble-captions.md
It's the source of truth for request and response shapes. The same page for people: https://dev.meta.ai/docs/cookbook/headlocked-speech-bubble-captions

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-voice-transcribe-1.0
- 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
- Keep keys on the server, which calls the API.
- Voices: asr/transcribe in DIARIZATION mode on a mono 16-bit WAV; skip turns with no transcript.
- People: POST /v1/files (purpose=user_data), then a streamed sam-3.1 call: input_text "people", input_video by file_id, metadata {"mask_encoding": "one_bit"}.
- Drop tiny people by area ratio, not by describing clothing.
- SAM video $0.20 per 1,000 frames, 50 minimum; voice $0.18 per audio hour.

Starter code (Python)
import asyncio, json, os

import httpx
from meta_sam_parser import decode_mask_to_raster, parse_responses_stream, video_segmentation_format
from openai import AsyncOpenAI

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


async def voices(wav):
    async with httpx.AsyncClient(timeout=600) as http:
        res = await http.post("https://api.meta.ai/v1/asr/transcribe", headers={"Authorization": f"Bearer {client.api_key}"},
                              data={"request": json.dumps({"model": "muse-voice-transcribe-1.0", "audioEncoding": "WAV", "mode": "DIARIZATION"})}, files={"audio": ("a.wav", open(wav, "rb"), "audio/wav")})
    res.raise_for_status()
    return [t for t in res.json()["turns"] if t["transcript"]]


async def people(mp4):
    upload = await client.files.create(file=open(mp4, "rb"), purpose="user_data")
    stream = await client.responses.create(model="sam-3.1", stream=True, metadata={"mask_encoding": "one_bit"}, input=[{"role": "user", "content": [
        {"type": "input_text", "text": "people"}, {"type": "input_video", "file_id": upload.id}]}])
    result = await parse_responses_stream(stream, video_segmentation_format()).final_result()
    return [(m, decode_mask_to_raster(m.mask)) for m in result.records if m.kind == "mask"]


async def main():
    turns, masks = await asyncio.gather(voices("audio.wav"), people("input.mp4"))  # in parallel

asyncio.run(main())

Done when
- Both analyses run in parallel, with progress for each.
- Each speaker maps to a person; their bubble shows only while they talk.
- Bubbles never cover a face and follow their person; the MP4 keeps the original audio.
- 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.