Connect, pay and edit—without website signup.

Start without a LyricPatch website account

The public POST /v1/agent/sessions endpoint offers a private session with 40 non-expiring credits for $1.99, paid through x402 with USDC on Base. It does not need an existing LyricPatch login or agent key. The server creates a separate owner identity and issues an API key only after funding is confirmed.

1. Generate lp_session_ followed by 64 cryptographically random hex characters. Save that secret securely before the first request; send it in X-LyricPatch-Session on every bootstrap and recovery request.
2. Read GET /v1/agent/sessions/offer for public service information, or discover get_service_info through anonymous MCP initialization and tool listing. Then POST the session request: HTTP 402 returns the payment requirements and legal version. If you omit the session header, the server provides a session secret; a lost initial response is why generating your own first is recommended.
3. Confirm adult eligibility, current terms, rights to the recording/lyrics/voices, spending authority and media-processing permission. Send each attestation only when it is true and actually authorized—not merely because an example contains it.
4. Use an authorized x402-capable wallet to sign the offered payment. Retry the same session with PAYMENT-SIGNATURE and the confirmed attestations. An ordinary HTTP client cannot sign for your wallet.
5. On confirmed funding, save api_key privately. If payment is pending, recover the existing session and resume the same purchase when needed. Never create a new session as a payment retry.

# HTTP protocol sketch — wallet signing is handled by your x402 client.
# FIRST generate "lp_session_" + secrets.token_hex(32) in your client.
# Persist it in a secret manager BEFORE making any network request.
# Use the SAME X-LyricPatch-Session value for this session on every retry.

POST /v1/agent/sessions
X-LyricPatch-Session: <your saved session secret>
Content-Type: application/json

{}

# 402: read PAYMENT-REQUIRED, the offer and current legal_version.
# Get actual permission for each attestation and the displayed purchase.
# Your wallet client signs this exact offer. Retry the SAME URL and secret:

POST /v1/agent/sessions
X-LyricPatch-Session: <the same saved session secret>
PAYMENT-SIGNATURE: <signature from your authorized x402 wallet>
Content-Type: application/json

{
  "legal_version": "<current version from the offer>",
  "adult_attested": true,
  "terms_accepted": true,
  "rights_attested": true,
  "spending_authorized": true,
  "media_processing_authorized": true
}

# The true values above are valid ONLY after actual delegated permission.
# 200 = confirmed funded session; store api_key privately.
# 202 = payment pending; do not start a new purchase/session.
# Recover using the SAME private session secret:

GET /v1/agent/sessions/current
X-LyricPatch-Session: <the same saved session secret>

# If payment needs resuming after its proof was recorded, POST the SAME
# session again without a new PAYMENT-SIGNATURE. Never buy a second session.
# Do not log session responses, session secrets, api_key or signed proofs.

Keep the session secret to resume its paid balance and recover its credential. There is no email recovery for a lost signup-free session secret. It is not a public transaction receipt or an identifier to share with support. Funding does not itself authorize generation, alternate versions, exports or publication.

A client must support the REST bootstrap, file transfer and x402 wallet authorization. MCP also requires Streamable HTTP and custom bearer headers. A capable host can obtain the funded key and connect it programmatically; the person does not need to create a key or configure a website account manually. A prompt alone does not give every chat assistant these capabilities.

1. Connect your credential

If you funded a signup-free session, use its returned API key and skip the account steps below. The following optional path is for people who want to use an existing website account and balance.

1. Sign in and create a key. This is an alternative to signup-free sessions: a person signs in and accepts the age, rights and use requirements.
2. Choose the permissions your agent needs. Set an expiration and a daily credit limit. The key is shown once; store it in a secret manager.
3. Fund the account with existing credits, one-time Stripe checkout, or an explicitly approved x402 purchase. New accounts have no welcome credits.

For a funded signup-free session, use its returned API key. For either credential, send Authorization: Bearer <key> to the API, never as a query parameter. Human website sessions manage account keys; signup-free clients retain their private session secret for recovery. REST base URL: https://api.lyricpatch.com.

Transport: Streamable HTTP
Server URL: https://api.lyricpatch.com/mcp
Authorization: Bearer <api_key from your funded session, or account agent key>

Public MCP metadata discovery: initialize, tools/list and get_service_info.
Fund a signup-free session over REST before using private MCP tools.
Capable hosts can bootstrap and connect the returned key automatically.
Store the key in your client's secret manager.
Never include a real key in a public configuration file.

Use an MCP client supporting Streamable HTTP and custom bearer headers. Keep the secret in its secure configuration, not an ordinary chat. Anonymous MCP supports initialization, tool listing and public service information only. Private MCP work requires a valid key; bootstrap creates one without manual website signup.

2. Make your first edit

Use MCP tool discovery for current argument schemas. The brief below describes the full workflow; it does not authorize your agent to choose lyrics, spend money or publish audio without your instructions. The agent supplies exact phrase timing or its own authorized timed transcript for the local matcher.

Use LyricPatch to edit audio I own or have permission to edit.

1. Check your client supports the REST/MCP and wallet workflow.
   If I have no key, explain the signup-free $1.99 / 40-credit session.
   Confirm my actual age, terms, rights, spending and media-processing
   permissions. Never assume these attestations or wallet approval.
   Save the session secret securely before the first request and reuse
   it on payment retries. Connect only after funding is confirmed.
2. Check available tools, my private balance, permissions and limits.
   Upload my MP3 with permission and wait for preparation to finish.
3. Supply exact phrase timestamps, or use your own authorized timed
   transcript with LyricPatch's local phrase matcher. LyricPatch does
   not transcribe the whole song for this. Ask about ambiguous matches.
   Use a 0.1–6-second selection and only my approved words. Optional
   LyricPatch transcription covers only a selected clip, with permission.
4. Get the generation quote. Tell me its credit cost and ask before
   spending. Do not generate alternate versions automatically.
5. Generate the approved change, then poll its status at the server's
   recommended interval. Let me compare original and new audio.
6. Apply only the version I approve. Quote the 5-credit MP3 or WAV
   export and ask before preparing it.
7. Download the ready file before the project's 24-hour expiry.

If credits are short, ask before purchasing a pack. Show its price,
network and any wallet fees. Never use another wallet or retry a
payment with a new session or purchase identifier unless I approve it.
Keep session credentials private; a lost session secret has no email recovery.

Start with a 3–4-second phrase and match the original rhythm and approximate syllable count. Supply accurate original words. Optional transcription finds only the selected clip’s words—not the whole song.

Find a phrase in the agent’s timed transcript

A request like “change X to Y” still needs the location of X. The calling agent provides exact timestamps directly, or supplies its own transcript with word-level timing to POST /v1/agent/projects/{project_id}/phrase-matches. LyricPatch matches that supplied text locally and returns candidate selections; this endpoint does not transcribe audio or send a whole song to OpenAI.

The equivalent MCP tool is match_phrase, with project_id, target_phrase and words. It requires the transcribe scope and a prepared project. The JSON body contains target_phrase and words, an array of {text, start_seconds, end_seconds}. Use the prepared project’s actual source timing. The calling client is responsible for any separate transcription, media-sharing permission and processing terms.

# The calling agent supplies its own authorized transcript and timings.
# This example assumes a prepared project containing these time positions.
# LyricPatch matches the supplied words locally; it does not transcribe audio.
curl 'https://api.lyricpatch.com/v1/agent/projects/<project-id>/phrase-matches' \
  -H "Authorization: Bearer $LYRICPATCH_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"target_phrase":"welcome home","words":[
        {"text":"welcome","start_seconds":30.0,"end_seconds":30.8},
        {"text":"home","start_seconds":30.8,"end_seconds":31.4}
      ]}'

# Read match_status and candidates. Never choose an ambiguous match silently.
# Review the audio and supplied timings; they are not independently verified.
# Use approved, valid start_sample/end_sample in POST /projects/{id}/edits.
# Then save original/replacement lyrics, quote generation and get approval.

• The synchronous response identifies source: agent_supplied_transcript, a match_status and candidate sample/second ranges. No queue or polling is needed for the matcher.
• matched is a candidate, not proof the audio says those words. transcript_verified is false, and a candidate’s score measures text similarity, not audio or timing confidence. Review the audio and check selection_valid before generation. For ambiguous, ask which occurrence the owner wants; do not silently choose one.
• not_found, too_long or too_short need corrected source timing/text or a different approved selection. Do not invent a successful match.
• Selections still need to fit 0.1–6 seconds. Requests allow up to 5,000 timed words in ascending start-time order, 100 characters per word and 100,000 transcript characters total. The target is limited to 300 characters and 40 words. All timings must fit the actual source duration.
• Matching has no separate credit charge and does not persist the supplied transcript or candidates. Saving an edit stores its chosen timing and lyrics as normal private project content.

The ordinary “Find the words for me” option remains separate: with permission, it sends only a preselected 0.1–6-second clip to OpenAI. It does not locate a phrase across a whole song.

REST reference and MCP equivalents

These authenticated REST paths are relative to /v1/agent. Send your funded-session or account bearer key on these requests. Public session bootstrap and recovery instead use X-LyricPatch-Session, as shown above. Successful REST responses are JSON objects (or a list for projects); deletes return 204. Errors include a machine-readable code. MCP exposes the same operations as tools.

Every mutating project request below needs a unique Idempotency-Key header, 8–128 characters. If a body also includes idempotency_key, it must match the header. Keep both inputs and the same key when recovering a timed-out request. Never reuse a key for a different action.

Selection timing

Read the prepared source’s sample_rate. Convert seconds to sample positions: round(seconds × sample_rate). At 44,100 Hz, a 0–4-second selection is start_sample: 0, end_sample: 176400. Supply the signed upload response’s fields as headers when sending the raw MP3 bytes to its PUT URL. Do not send your LyricPatch authorization header to the storage URL.

Quote before spending

Quotes bind the current selection, lyrics or accepted versions. Read credits and expires_at. A changed or expired quote needs a fresh quote and renewed cost approval. The example below shows the paid steps once the project and edit are ready.

# Assumes an uploaded, prepared project and a draft with saved lyrics.
# All IDs below come from actual earlier API responses.
# Use a fresh idempotency value for each NEW action, keeping it on retries.
curl 'https://api.lyricpatch.com/v1/agent/quotes' \
  -H "Authorization: Bearer $LYRICPATCH_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-song-generation-quote-001' \
  -d '{"operation":"generate","project_id":"<project-id>",
       "edit_ids":["<edit-id>"],"max_credits":4}'

# Inspect credits and expires_at. Only continue after user approval.
curl 'https://api.lyricpatch.com/v1/agent/generations' \
  -H "Authorization: Bearer $LYRICPATCH_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-song-generation-001' \
  -d '{"quote_id":"<quote-id>","idempotency_key":"my-song-generation-001"}'

# Read the returned batch ID; poll no faster than once every 3 seconds.
curl 'https://api.lyricpatch.com/v1/agent/batches/<batch-id>' \
  -H "Authorization: Bearer $LYRICPATCH_API_KEY"

# After reviewing and accepting a version, quote export separately:
curl 'https://api.lyricpatch.com/v1/agent/quotes' \
  -H "Authorization: Bearer $LYRICPATCH_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-song-export-quote-001' \
  -d '{"operation":"export","project_id":"<project-id>",
       "format":"mp3","max_credits":5}'

# After approval, POST /v1/agent/exports with this quote_id and a NEW
# idempotency_key for the export. Keep that key for retries of this export.

3. Credits and x402 payments

Account agents and the website share their account’s balance. A signup-free session has its own balance and begins with the $1.99 / 40-credit pack; its funded API key can use the same credit-purchase endpoints below. Generation costs one credit per selected second, rounded up per change. Each successful alternate version costs credits again. A new finished-song MP3 or WAV costs 5 credits to prepare. Re-downloading the same ready file costs nothing extra while the project is available.

A purchase needs separate wallet approval

A payments-scoped key can create a credit purchase. x402 uses USDC on Base. An authorized x402-capable wallet client signs the payment; an API key cannot access your wallet or grant wallet-spending permission.

1. Create a purchase with a pack and unique idempotency key. Read the returned amount and credit quantity.
2. Ask the owner to approve the purchase and any wallet/network fees. POST to the returned pay_url for an HTTP 402 challenge in PAYMENT-REQUIRED.
3. Have the wallet client handle the challenge, then retry that same payment request with PAYMENT-SIGNATURE.
4. Check the existing purchase until payment is confirmed and credits appear. A timeout is not permission to start another purchase.

# Keep the API key in your environment, not the command history.
# This key needs the payments scope.
curl 'https://api.lyricpatch.com/v1/agent/payments' \
  -H "Authorization: Bearer $LYRICPATCH_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"pack_id":"credits_40","idempotency_key":"your-unique-purchase-id"}'

# Response: id, status, pay_url, amount_cents, currency, credits.
# Get user approval, then have an x402-capable wallet client handle
# the 402 challenge at pay_url. Plain curl cannot sign a payment.
# After paying, check this SAME purchase instead of creating another:
curl 'https://api.lyricpatch.com/v1/agent/payments/<purchase-id>' \
  -H "Authorization: Bearer $LYRICPATCH_API_KEY"

Purchase endpoints: POST /v1/agent/payments, GET /v1/agent/payments/{id}, and POST /v1/agent/payments/{id}/pay. Buying credits and approving a generation/export are separate actions. Website checkout remains available through Stripe.

4. Scope access to the task

Keys act only on their owner identity: the existing account or the isolated signup-free session. A daily credit limit is not a wallet budget: configure wallet authorization separately. Revocation blocks new requests but does not automatically cancel already-started work. Use cancellation when needed.

Agent access lets you create, inspect and revoke keys. Key-management routes at /v1/account/agent-keys require a human’s signed-in session, not an agent key.

5. Limits and privacy

• MP3 uploads: up to 100 MB and 15 minutes. Keep your original copy.
• Selected phrases: 0.1–6 seconds, starting anywhere including zero. 3–4 seconds is a recommendation, not a limit.
• Up to 32 non-overlapping changes per song. Account balance and key budget must cover new paid work.
• Generation supports English and Chinese. Quality varies; review every output.
• Audio, lyrics, versions and exports expire 24 hours after project creation. Reopening does not reset expiry.
• Projects are private to their account or isolated signup-free session and its authorized agents. Signed file links are temporary credentials: never publish or log them.
• LyricPatch does not train models on uploads. Your chosen agent client is separate; review its privacy settings before sharing audio or lyrics.

For adults 18+. Have the needed permissions for recordings, lyrics and identifiable voices. Agent access does not bypass the Terms, Acceptable Use Policy, or account restrictions.

6. Recover without repeating charges

• Save identifiers and the session secret. Keep project, work, quote and purchase IDs, and store session credentials privately. A timeout is not proof of failure. Recover the existing signup-free session; never buy another session just because a response was lost.
• Poll existing work. Follow returned retry guidance; do not start repeated generations while waiting.
• Refresh a conflict. If a project or quote changed, fetch fresh state and obtain approval for the new cost.
• Only unfinished costs are restored. Failed or confirmed-cancelled work returns reserved credits. Successful work remains charged.
• Stop on authorization errors. Revoked keys, missing scopes, exhausted budgets and suspended accounts need owner action—not a workaround.

Email [email protected] with the work or purchase ID for help. Never send session secrets, API secrets, wallet private keys or signed file URLs.