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/vision. 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 Image Analysis API

Analyze and describe image content using AI vision models. Ask questions about any image.

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

Step 1: Initial Request

Send the image (base64 or data URI) with your question. You will receive a 402 Payment Required response.

curl -X POST https://sats4ai.com/api/l402/vision \
-H "Content-Type: application/json" \
-d '{
  "image": "data:image/png;base64,iVBORw0KGgo...",
  "prompt": "What objects are in this image?",
  "model": "Vision Chat"
}' \
-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/vision \
-H "Content-Type: application/json" \
-H "Authorization: L402 <YOUR_MACAROON_STRING_HERE>:<YOUR_PREIMAGE_HERE>" \
-d '{
  "image": "data:image/png;base64,iVBORw0KGgo...",
  "prompt": "What objects are in this image?",
  "model": "Vision Chat"
}'

Expected Successful Response:

{ "content": "The image shows a cat sitting on a wooden table near a window..." }

Request Body Parameters

image: string (required)

Base64-encoded image or data URI (e.g. data:image/png;base64,...). If no prefix is provided, data:image/png;base64, is assumed.

prompt: string

Question to ask about the image. Default: "What's in this image?"

model: string (required)

Accepted Values: "Vision Chat"