recoup-content-create

Recoup Content Create

The anchor command for the recoup-content. Use this on first install to confirm the plugin works end-to-end, and as the default front door for "make a video for [artist]" requests.

This skill is user-invoked — the user types /recoup-content-create <artist-name> and the harness invokes it with $ARGUMENTS populated. It is self-contained: the default async path below runs without any other skill. For granular control (swapping a single stage), it points to the short-video skill in the Recoupable skills library.

Arguments

The user invoked this with: $ARGUMENTS

Expected shape: <artist-name> [--template <template-name>]

• <artist-name> — the artist to generate content for. Required. If the user didn't supply one, AskUserQuestion to collect it.
• --template <name> — optional. Defaults to artist-caption-bedroom. Override based on user cue ("with the album cover" → album-record-store, etc.).

Required environment

• RECOUP_API_KEY set in the shell environment, OR a Privy access token if running inside chat (pass it as -H "Authorization: Bearer $RECOUP_ACCESS_TOKEN" instead of x-api-key).
• An artist record already exists for the requested artist on the user's first org. If not, run the create-artist skill (Recoupable skills library) first.

What it does

1. Resolves the artist's account_id (from artist name + the user's first org).
2. Picks a template (defaults to artist-caption-bedroom if not supplied).
3. Fires POST /api/content/create to start the async pipeline server-side.
4. Polls /api/tasks/runs?runId={runId} every ~10 seconds until status is COMPLETED, FAILED, CANCELED, or CRASHED.
5. Reads the run output: videoSourceUrl, imageUrl, captionText, template, lipsync, and the audio metadata.
6. Lands the user on the final video URL with the caption text printed below it.

The async pipeline is the agent-safe path — synchronous calls to /api/content/video routinely take 60–180 seconds and time out inside most agent shells.

Steps the agent must execute

1. Resolve the artist's account_id

ORG_ID=$(curl -sS "https://api.recoupable.com/api/organizations" \
  -H "x-api-key: $RECOUP_API_KEY" | jq -r '.organizations[0].id')

ARTIST_ACCOUNT_ID=$(curl -sS "https://api.recoupable.com/api/artists?org_id=$ORG_ID" \
  -H "x-api-key: $RECOUP_API_KEY" \
  | jq -r --arg name "$ARTIST_NAME" '.artists[] | select(.name == $name) | .account_id')

Use account_id, not id — id is the artist row's primary key, account_id is the underlying account that owns it. Passing the wrong one returns a 404 from /api/content/create. If no match, the artist record doesn't exist yet — run the create-artist skill first.

2. Trigger the async pipeline

TEMPLATE="${TEMPLATE:-artist-caption-bedroom}"

RUN_IDS=$(curl -sS -X POST "https://api.recoupable.com/api/content/create" \
  -H "x-api-key: $RECOUP_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg artist "$ARTIST_ACCOUNT_ID" --arg template "$TEMPLATE" \
        '{artist_account_id: $artist, template: $template}')" \
  | jq -r '.runIds[]')
RUN_ID=$(echo "$RUN_IDS" | head -1)

3. Poll until terminal

until STATUS=$(curl -sS "https://api.recoupable.com/api/tasks/runs?runId=$RUN_ID" \
                 -H "x-api-key: $RECOUP_API_KEY" \
               | jq -r '.runs[0].status') && \
      [[ "$STATUS" =~ ^(COMPLETED|FAILED|CANCELED|CRASHED)$ ]]; do
  sleep 10
done

4. Read the output and land the user

curl -sS "https://api.recoupable.com/api/tasks/runs?runId=$RUN_ID" \
  -H "x-api-key: $RECOUP_API_KEY" \
  | jq '.runs[0].output'
# -> { videoSourceUrl, imageUrl, captionText, template, lipsync, audio: {...} }

See Tasks Runs for the full status enum and the CreateContentRunOutput schema.

What "complete" looks like

The command finishes when:

• The poll loop has seen a terminal status (COMPLETED is the happy path).
• output.videoSourceUrl is a fetchable URL.
• output.captionText is a non-empty string.

Print both to the user. If status is FAILED, CANCELED, or CRASHED, surface the error from runs[0].error and stop — don't claim success.

When to reach for the other skills

This async front door is the default. Use the underlying skills directly when:

• The user wants to swap a single stage (different caption length, different motion prompt, different reference image), inspect intermediate outputs, or supply their own audio. Use the short-video skill (Recoupable skills library) — its bundled manual covers the five-step recipe, and it explains resolving the underlying song.mp3.
• The user wants to generate one capability in isolation (just an image, just a caption). Use the content-creation skill (Recoupable skills library).
• The artist doesn't exist yet. Use the create-artist skill (Recoupable skills library) first.