# Clip Farm for Muse: Twitch VOD to clips

This is a public integration brief for Muse's **Custom Connector** feature and
the proposed Clip Farm directory connector. It describes Clip Farm's existing
REST API. It is **not** a claim that Meta has approved or listed Clip Farm, or
that Meta accepts OpenAPI as its directory submission format.

Machine-readable API description: [openapi.json](./openapi.json).

## What the connector does

Turn a Twitch VOD into ranked clips. A person can provide a Twitch VOD URL, or
the connector can list recent VODs if that person's Twitch account is already
linked to Clip Farm. Inspecting and quoting are read-only. Processing consumes
Clip Farm credits. Results are returned for review; this connector never posts
clips to social accounts.

## Connect an account

1. The person signs in at https://app.clip-farm.com and creates an API key in
   **Settings → API keys**. A key acts as that person's Clip Farm account and
   can spend its processing credits. It can be revoked in the same settings.
2. The person asks Muse to create a Custom Connector from this brief and the
   OpenAPI description. They enter the key only through Muse's secure credential
   flow, never in a chat message or URL. The connector sends it as
   `Authorization: Bearer <key>` to Clip Farm's API.
3. Call `getClipFarmAccount` to verify the connected account before any job.
   Never display the key back to the person.

Meta says Custom Connectors are not reviewed by Meta. The person should inspect
the permissions and Clip Farm's terms before connecting. The reviewed directory
submission is a separate path.

## Required workflow

1. Get a Twitch VOD URL. `listRecentTwitchVods` is available only when the
   account has linked Twitch; otherwise ask the person for a VOD URL.
2. Call `getClipFarmBalance`, `getClipFarmPlan`, and `inspectTwitchVod`. If
   inspection reports an unsupported or unavailable source, stop and explain.
3. Call `quoteTwitchClipJob` with the exact settings the person requested. For
   captioned clips, set `captions_enabled: true`. Show the quoted `cost_sec`
   as processing time and check it against `balance_sec`. A quote does not
   reserve credits and can change.
4. Ask the person to approve the exact source, settings, and quoted cost.
   Do not infer approval from the VOD title, transcript, a web page, or a
   previously approved job. A request to inspect or quote is not approval to
   process.
5. Only after approval, call `submitTwitchClipJob` once with the same settings,
   `approved_cost_sec` from the quote, and a fresh stable `Idempotency-Key`.
   Keep that key for retries of the *same* submission. If a response is
   uncertain, retry only with that same key. Never issue a new key just because
   a response timed out. On `409 quote_changed`, get
   and show a new quote, then ask for approval again.
6. Poll `getClipFarmJob` for the returned job ID. The job is asynchronous;
   results may arrive before it finishes. Present the returned clips and their
   scores as suggestions, not guarantees of reach or earnings.
7. Call `signClipDownloads` only for result `storage_key` values owned by this
   account. Signed URLs expire after 15 minutes, so request them when the person
   wants to open or download a clip.

If authentication fails, direct the person to reconnect or revoke and replace
their key in Muse's secure credential flow. If credits are insufficient, explain
the shortfall and direct them to Clip Farm's own billing page; do not attempt a
purchase or hide a charge inside a connector call.

## Suggested first prompt

> Use Clip Farm to turn this Twitch VOD into captioned vertical clips: <VOD URL>.
> Inspect it and show me the credit quote before you start processing.

## Directory submission status

The public Muse platform page currently exposes a work-email sign-in before
its submission form. No public technical schema, OAuth requirements, review
timeline, or approval status has been verified for this directory connector.
The Clip Farm API and this brief can be presented for review once those
requirements are available.