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/3d-model. 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 3D Model Generation API

Generate a 3D model from an image. Upload a photo of an object and receive a downloadable 3D model.

API Endpoint: https://sats4ai.com/api/l402/3d-model

Step 1: Initial Request

Send the image as a base64 data URI. You will receive a 402 Payment Required response.

curl -X POST https://sats4ai.com/api/l402/3d-model \
-H "Content-Type: application/json" \
-d '{
  "image": "data:image/png;base64,iVBORw0KGgo..."
}' \
-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/3d-model \
-H "Content-Type: application/json" \
-H "Authorization: L402 <YOUR_MACAROON_STRING_HERE>:<YOUR_PREIMAGE_HERE>" \
-d '{
  "image": "data:image/png;base64,iVBORw0KGgo..."
}'

Expected Successful Response:

{ "modelUrl": "https://..." }

Note: 3D model generation may take up to 5 minutes. The request will wait until the model is ready.

Request Body Parameters

image: string (required)

Base64 data URI of the source image. Must include the data URI prefix.

Accepted formats: image/png, image/jpeg, image/webp

Example: "data:image/png;base64,iVBORw0KGgo..."