L402 File Conversion

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:

Image Text SMS Video Video from Image Music Speech Vision 3D Model File 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"

Make Your First Request: Send your initial API request to the desired service endpoint.
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

Pay the Lightning Invoice: Use any Lightning-compatible wallet.
Get the Preimage: After payment, your wallet provides a preimage (your "proof of payment").
Make Your Second Request (with Payment Proof): Send the exact same request as in Step 1 tohttps://sats4ai.com/api/l402/file-conversion. 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 File Conversion API

Convert files between formats (e.g. DOCX to PDF, PNG to WEBP). Powered by CloudConvert.

API Endpoint: https://sats4ai.com/api/l402/file-conversion

Step 1: Initial Request

Send the file (base64-encoded) with source and target formats. You will receive a 402 Payment Required response.

curl -X POST https://sats4ai.com/api/l402/file-conversion \
-H "Content-Type: application/json" \
-d '{
  "file": "<base64-encoded-file-data>",
  "file_name": "document.docx",
  "extensionFrom": "docx",
  "extensionTo": "pdf"
}' \
-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/file-conversion \
-H "Content-Type: application/json" \
-H "Authorization: L402 <YOUR_MACAROON_STRING_HERE>:<YOUR_PREIMAGE_HERE>" \
-d '{
  "file": "<base64-encoded-file-data>",
  "file_name": "document.docx",
  "extensionFrom": "docx",
  "extensionTo": "pdf"
}'

Expected Successful Response:

{ "url": "https://..." }

The returned URL is a temporary download link for the converted file.

Request Body Parameters

`file`: string (required)

Base64-encoded file data. Can include a data URI prefix (it will be stripped automatically).

`file_name`: string (required)

Original file name (e.g. "document.docx").

`extensionFrom`: string (required)

Source file format (e.g. "docx", "png", "mp4").

`extensionTo`: string (required)

Target file format (e.g. "pdf", "webp", "mp3").