Skip to main content

L402

How to use it as an API

Understanding L402: Pay-Per-Use APIs with Bitcoin 💡

L402 is a "Bitcoin Standard" for APIs. It lets different applications "talk" to each other securely. Instead of usernames, passwords, and credit card details, it uses a clever combination of:

  • Macaroons: These are like special, tamper-proof digital "tickets" or "tokens" that grant access.
  • Lightning Network: This allows for instant, low-fee Bitcoin payments.

Together, they create a secure and private way to access paid services. You only pay for what you use.Learn More

Choose a service to get started:

ImageTextSMSVideoVideo from ImageMusicSpeechVision3D ModelFile Conversion

How to Use Our L402 Services: A Step-by-Step Guide ⚙️

Using an L402-protected service involves a simple two-step process: first, you request access and get a "bill" (invoice), and second, you pay the bill and present your "proof of payment" (preimage) to use the service.

Step 1: Request Access & Get Your "Ticket" and "Invoice"

  1. Make Your First Request: Send your initial API request to the desired service endpoint.
  2. Receive a 402 Payment Required Response: This is normal! The response header will contain:
    • A Macaroon (your access "ticket").
    • An Invoice (a Lightning Network payment request).
    www-authenticate: L402 macaroon="<YOUR_UNIQUE_MACAROON>", invoice="<LIGHTNING_INVOICE_STRING>"

Step 2: Pay the Invoice & Use the Service

  1. Pay the Lightning Invoice: Use any Lightning-compatible wallet.
  2. Get the Preimage: After payment, your wallet provides a preimage (your "proof of payment").
  3. Make Your Second Request (with Payment Proof): Send the exact same request as in Step 1 tohttps://sats4ai.com/api/l402/music. This time, include the `Authorization` header:
    Authorization: L402 <YOUR_UNIQUE_MACAROON>:<YOUR_PREIMAGE>

❗ Important Notes:

  • Identical Requests: The body/data of your first and second requests must be exactly the same.
  • Not a Stream (Currently): Our L402 services do not currently support streaming responses.

Using the L402 Music Generation API

Create original songs with AI-composed music and vocals from a style prompt and lyrics.

API Endpoint: https://sats4ai.com/api/l402/music

Step 1: Initial Request

Send your music parameters. You will receive a 402 Payment Required response.

curl -X POST https://sats4ai.com/api/l402/music \
-H "Content-Type: application/json" \
-d '{"prompt":"upbeat pop song about summer vibes","lyrics":"Walking on the beach, sun is shining bright, every day feels right","model":"Music Generation","sample_rate":44100,"bitrate":256000,"audio_format":"mp3"}' \
-i

Expected Response Headers:

www-authenticate: L402 macaroon="<YOUR_MACAROON>", invoice="<LIGHTNING_INVOICE>"

Step 2: Pay the Lightning Invoice

Pay the invoice and save the preimage.

Step 3: Final Request

Send the exact same request with the Authorization header.

Important: The JSON payload must be identical to Step 1.

curl -X POST https://sats4ai.com/api/l402/music \
-H "Content-Type: application/json" \
-H "Authorization: L402 <YOUR_MACAROON_STRING_HERE>:<YOUR_PREIMAGE_HERE>" \
-d '{"prompt":"upbeat pop song about summer vibes","lyrics":"Walking on the beach, sun is shining bright, every day feels right","model":"Music Generation","sample_rate":44100,"bitrate":256000,"audio_format":"mp3"}'

Expected Successful Response:

{ "audioUrl": "https://..." }

Request Body Parameters

prompt: string (required)

Music style description. 10-300 characters.

lyrics: string (required)

Song lyrics. 10-600 characters.

model: string (required)

Accepted Values: "Music Generation"

sample_rate: integer

Audio sample rate. Default: 44100

bitrate: integer

Audio bitrate. Default: 256000

audio_format: string

Accepted Values: "mp3", "wav", "pcm". Default: "mp3"