Docs

Start with Lector API

Quickstart, endpoint guidance, and API examples.

Authenticate with your API key

Send your API key in the Authorization header as a Bearer token. 

Authorization: Bearer YOUR_API_KEY

Quickstart

curl -X POST https://api.lectorai.app/v1/tts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from Lector",
    "voice": "alloy",
    "delivery": "url"
  }'

Choose the right endpoint

  • Use /v1/tts when you already have the text
  • Use /v1/listen-content when your app already extracted the content
  • Use /v1/listen-url when Lector should fetch and read a public page
  • Use /v1/listen-document or /v1/listen-document-url for documents
  • Use /v1/listen-image or /v1/listen-image-url for OCR-based image reading

Choose how audio is returned

  • stream → real-time playback
  • url → hosted audio file

Use stream for immediate listening and url for async workflows, agents, and saved playback.

Examples by input type

Text

Use this when you already have the text. 

curl -X POST https://api.lectorai.app/v1/tts \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "text": "Hello from Lector",
        "voice": "alloy",
        "delivery": "url"
      }'

URL

Use this when you want Lector to read a public web page. 

curl -X POST https://api.lectorai.app/v1/listen-url \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://example.com/article",
        "delivery": "url"
      }'

Content

Use this when your app already extracted or rendered the content. 

curl -X POST https://api.lectorai.app/v1/listen-content \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "content": "Paste the content you want Lector to read.",
        "delivery": "url"
      }'

Document URL

Use this when you want Lector to read a public document from a URL. 

curl -X POST https://api.lectorai.app/v1/listen-document-url \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://example.com/file.pdf",
        "delivery": "url"
      }'

Upload a document

Use this when you want to upload a local PDF or document file directly. 

curl -X POST https://api.lectorai.app/v1/listen-document \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -F "file=@/path/to/file.pdf" \
      -F "delivery=url"

Image URL

Use this when you want Lector to read text from a public image URL. 

curl -X POST https://api.lectorai.app/v1/listen-image-url \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://example.com/image.png",
        "delivery": "url"
      }'

Upload an image

Use this when you want to upload a local image file directly. 

curl -X POST https://api.lectorai.app/v1/listen-image \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -F "file=@/path/to/image.png" \
      -F "delivery=url"

Choose the right request format

Lector accepts either JSON or multipart form-data depending on the endpoint.

Use JSON for

  • /v1/tts
  • /v1/listen-url
  • /v1/listen-content
  • /v1/listen-document-url
  • /v1/listen-image-url

Use multipart form-data for

  • /v1/listen-document
  • /v1/listen-image

Common errors

  • 400 → invalid input or missing required fields
  • 401 → missing or invalid API key
  • 402 → payment required before API access can continue
  • 413 → input too large for the endpoint
  • 500 → internal server error

402 PAYMENT_REQUIRED

Lector can return a structured payment-required response when API billing or access must be completed before the request can continue.

  • Your app or agent makes a request
  • Lector returns payment_required with the next billing step
  • The user or agent completes billing
  • The same request can be retried after activation

Access and billing

API access and billing are managed through the dashboard. Use billing status to check whether an account is ready to make requests or needs billing action first.

  • Use an API key to authenticate requests
  • Complete billing via the checkout link returned by the API if required
  • Check access with /v1/billing/status
  • Retry the request once billing is active

Billing status example

curl -X GET https://api.lectorai.app/v1/billing/status \
      -H "Authorization: Bearer YOUR_API_KEY"

API key handling

API keys are secrets and must be stored securely. Keys are only revealed once when generated so make sure they are saved immediately.

Canonical flows

Listen and summarize

Use Lector to convert text or a URL into audio, then pass the same source into your summarization layer.

Convert and store

Generate hosted audio with delivery=url, then store the returned URL in your application or workflow.

Monitor continuously

Use Lector in scheduled systems that repeatedly read updated public pages, documents, or images.

Agent-triggered billing

If access is not active, handle payment_required, complete billing, and retry automatically or with user confirmation.

Billing and retry flow

If an account does not have active API access, Lector can return a structured payment-required response that points the user or agent to the billing flow.

  • Call the endpoint
  • Receive payment_required if billing action is needed
  • Complete checkout
  • Retry the same request

Ready to build with Lector?

Go to API page Open Dashboard