Media Proxy

media-proxy

The foundation capability for paid media in the video-ad pipeline. It fixes the auth-path conflict where engine scripts called FAL/ElevenLabs directly (billing the wrong account): all paid calls now go through <api_base>/api/internal/{fal-proxy,elevenlabs-proxy} with ?token=&agent_id=, which bills the Ads agent.

Crash-resume (never lose / double-bill a paid render)

A FAL submit BILLS immediately, but the local backend can blip during a multi-minute render. Two built-in protections (automatic for every capability that imports this):

• Poll-through-outage — _fal_run's poll loop re-attaches to the same status/result URL through connection refused / timeout blips instead of crashing.

• Persist + resume — each submit's request_id + poll URLs are written to ~/.gooseworks/pending-fal-jobs/. If the poller still dies, re-attach instead of re-firing (re-firing double-bills): resume_fal(request_id) in Python, or the CLI:

  resume.py --list                              # resumable (submitted, unfinished) jobs
  resume.py --request-id <id> --out final.mp4   # poll to completion + download

  resume_fal NEVER re-submits, so it can't double-charge.

• Poll timeout never resubmits (GOOSE-3729) — polling gives up after default_poll_timeout(model): 1800s for video / lipsync / audio-driven models, 600s for images (GW_FAL_POLL_TIMEOUT_S overrides; timeout_s= per call). A timeout raises FalPollTimeout carrying .request_id + .model_path — the job is still running and already paid for. Re-attach with resume_fal(e.request_id); never call fal_generate* again for it (a veed/fabric lipsync once finished 26s after a 600s poller quit, and the retry paid for a second identical job).

• Proxy dedupe back-stop — the fal proxy returns the already-running job for an identical submit (same agent + model + body) within 30 min, so an accidental resubmit re-attaches instead of paying twice (response header x-gw-deduped: 1). For a deliberate re-roll of the same input (want a new take), pass new_take=True (fal_generate(..., new_take=True) / fal_generate_video(...)), which sends x-gw-no-dedupe: 1 (raw HTTP callers: that header or ?dedupe=0).

• Pass input_digest= for any piece you save as an ingredient, so a resumed run never pays twice. The body-match dedupe above breaks after a sandbox restart: the resumed run re-uploads its inputs (voiceover, stills) and gets NEW urls, so the body differs. fal_generate*(..., input_digest=d) sends x-gw-input-digest: d; the proxy then dedupes on (agent + model + digest) for 24 h and returns the job you already paid for. Use the same stable digest you save with media_upload (see below). If that job's result has since expired at fal, the poll fails: retry once with new_take=True.

Policy rejections are final: surface, do not retry (QA-14)

When fal refuses a request on policy grounds, _fal_run (and so fal_generate*) raises FalPolicyRejection, a RuntimeError subclass, so old except RuntimeError handlers still work. Policy grounds means a likeness of a real person ("likenesses of real people", "real person", "public figure"), content_policy_violation, partner_validation_failed, or NSFW / safety checker.

• Every body shape is read. fal's detail as a list of {msg, type, loc, ctx}, a dict or a string; a top-level type/code/error; the GooseWorks MCP wrapper {"error": {"code": "provider_validation_failed", "status": 422, "detail": <fal body>}}; and a failed job_get reply {"status": "failed", "error": "fal returned HTTP 422 for the result.", "result": {"detail": <fal body>}} (fal reports most failed generations as COMPLETED plus a 422 on the result). Before this, a body with both msg and type kept the message and lost the type, so the rejection looked like a generic error.

• When it counts as policy. An explicit policy code (content_policy_violation, partner_validation_failed, content_blocked) at any status, or a policy phrase (likeness, public figure, usage guidelines, risk control, moderation, blocked for safety, NSFW, flagged by the safety checker) on an explicit 4xx that is not 408 or 429. Input errors such as "Could not detect a real person's face" or "enable_safety_checker cannot be disabled" are not policy. A rejection on a 5xx, 408 or 429 is surfaced but never recorded.

• What it carries: reason (the provider's words), kind (likeness | partner_validation | content_policy | nsfw), error_type, request_id, http_status, stage, charged and charge_note. charged is False for an explicit provider 4xx: the GooseWorks proxy debits only a successful response and releases the hold on a 4xx (read from the proxy code, not yet confirmed on a real rejection). It is None (unknown) for a job that failed after it was accepted.

• The exact request is recorded in ~/.gooseworks/rejected-fal-requests/<key>.json, next to pending-fal-jobs/ (GW_FAL_REJECTIONS_DIR overrides). The key is a digest of the model plus the canonical JSON payload (sorted keys), and also of input_digest when one is passed.

• An identical request is refused before any network call, with the same exception and from_ledger=True: "surface, do not retry: this exact request was already rejected by the provider for ...; change the inputs (image, prompt, model) to try again". new_take=True does not bypass it: a re-roll of a rejected payload is still the same payload. Any change to the prompt, an image, the seed or the model is a new request and is sent.

• Inputs re-uploaded each run get new URLs, so the payload digest never matches twice. Pass input_digest= over the inputs' content, as create-creator-takes-h3/run_takes.py and render-street-interview/single_gen.py do. The ledger then matches on that too. refuse_if_rejected(model, input_digest=d) checks before you upload anything.

• A caller's input_digest is a permanent refusal key. It must cover EVERY input that is sent: the prompt, every setting (duration, resolution, aspect ratio, audio, seed) and the content of every input file. Simplest: input_digest(model, payload) over the real payload with each uploaded URL replaced by {"sha256": <file hash>}. Leave an input out and a run that changed only that input (a new, acceptable image) is refused.

• Exit code: scripts exit with POLICY_EXIT (3). The MCP relay also exits 3; the relay prints [mcp-relay], a rejection prints "surface, do not retry".

• Non-policy errors (an unreadable image URL, a bad duration) stay a plain RuntimeError with the provider's message and type, and are never recorded.

• Every refusal names its record: the ledger file and whether it matched the exact payload or the caller's input_digest.

• Clearing a record is a user-approved action. Only when the user explicitly approves, e.g. because the provider changed its policy:

  python3 media_proxy.py rejections        # list recorded rejections (key, model, reason, request id)
  python3 media_proxy.py forget <key>      # clear one record (all its keys); USER-APPROVED ONLY

  forget_rejection(key) does the same in Python. It only ever deletes ledger records: it takes the 32-hex key (or that record's filename or path inside the ledger directory) and refuses anything else, such as another .json file or a file without a keys field. Agents never clear a record on their own to get a retry through.