Docs

Start with Lector API

Quickstart, endpoint guidance, and API examples.

Get your API key

Before calling the Lector API, activate API access and reveal your API key from your Dashboard.

1. Sign in

Sign in to Lector with your email and confirm your email address.

2. Open your Dashboard

Go to your Dashboard to activate API access and choose an API plan.

3. Reveal your key once

Once your API subscription is active, reveal your API key and store it securely.

API keys are shown only one time and are never emailed.

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": "marin",
      "delivery": "url"
    }'

tts_provider and voice are optional. If omitted, Lector uses your account's default provider and voice.

Choose a voice provider

Lector can route text-to-audio requests through supported voice providers. If no tts_provider is selected, Lector uses your account's default provider.

OpenAI

Available on Starter and higher. OpenAI is the default stable provider and supports alloy, ash, ballad, cedar, coral, echo, fable, marin, nova, onyx, sage, shimmer, and verse.

xAI

Available on Starter and higher. Use this when you want to request xAI-powered voice generation.

Gemini

Available on Growth and higher. If your plan does not include Gemini, Lector returns a structured provider access error.

Provider example

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",
        "tts_provider": "xai",
        "voice": "eve",
        "delivery": "url"
      }'

Choose the right endpoint

  • Use /v1/tts when you already have the text
  • Use /v1/listen-content when your app or agent 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

  • delivery=stream - direct audio response
  • delivery=url - signed audio file URL
  • delivery=async_url - background job for supported endpoints
  • delivery=auto - Lector chooses the delivery path

Auto is convenience. Explicit settings are control. Use auto when you want Lector to choose the best delivery path. Use url, stream, or async_url when you need exact behavior.

URL responses

delivery=url returns a temporary signed audio file URL in audio_url and output.url. Responses also include X-Audio-Url and Link headers. These links are useful for playback, download, and agent workflows; they are not branded Lector share pages.

Async jobs and callbacks

delivery=async_url returns a job and status flow. Completed async jobs include audio_url and output.url. callback_url is available for async-capable API workflows on supported endpoints.

  • Async-capable: /v1/tts
  • Async-capable: /v1/listen-content
  • Async-capable: /v1/listen-document and /v1/listen-document-url
  • Async-capable: /v1/listen-image and /v1/listen-image-url
  • /v1/listen-url currently supports url, stream, and auto, but not async_url or callback_url.

delivery=auto v0 mapping

  • /v1/tts -> url
  • /v1/listen-content -> url
  • /v1/listen-url -> url
  • /v1/listen-document and /v1/listen-document-url -> async_url
  • /v1/listen-image and /v1/listen-image-url -> url

callback_url with delivery=auto resolves to async_url only on endpoints that support callbacks. Auto does not change provider, voice, format, speed, pages, reading_order, extraction_mode, or other explicit options. The current 20,000 character hard limit remains, and auto does not introduce a lower character limit. For small documents, auto currently chooses async_url for reliability; developers who want immediate processing can explicitly request delivery=url or delivery=stream. async_url is for reliable background processing, not because it is always faster.

share_url, embed_url, hosted Lector audio pages, analytics, and branded cards are future features.

Document and image audio depends on the readable content Lector can extract from the source. Images and scanned documents are best-effort. Source quality, layout, handwriting, blur, and small text may affect results. For medical, legal, financial, or safety-critical content, users should check generated audio against the original.

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": "marin",
        "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 or agent 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

Check available capabilities

Developers and agents can call the capabilities endpoint to understand supported inputs, delivery modes, providers, voices, and plan-gated features before making a request. 

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

Common errors

  • 400 → invalid input or missing required fields
  • 401 → missing or invalid API key
  • 402 → payment required before API access can continue
  • 403 → provider or feature not available on the current plan
  • 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, access, or plan activation 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 authorized agent completes billing
  • The same request can be retried after activation

Example response

{
      "error": {
        "type": "payment_required",
        "requires_action": true,
        "action_required": "checkout",
        "retry_hint": "Complete checkout, then retry the same request."
      },
      "billing": {
        "checkout_url": "https://checkout.stripe.com/..."
      }
    }

403 Provider access denied

If a requested voice provider is not available on the current plan, Lector returns a structured provider_access_denied response. Your app or agent can switch to an allowed provider or guide the user to upgrade. 

{
      "error": {
        "type": "provider_access_denied",
        "code": "TTS_PROVIDER_NOT_AVAILABLE_ON_PLAN",
        "message": "Gemini requires Growth plan or higher.",
        "current_plan": "starter",
        "allowed_tts_providers": ["openai", "xai"],
        "recommended_plan": "growth"
      }
    }

Access and billing

API access is managed through the Dashboard and enforced by the API. Use billing status to check whether an account has active API access, which plan is active, and whether billing action is required.

  • Use an API key to authenticate requests
  • Call /v1/billing/status to check plan, subscription, and access state
  • If Lector returns payment_required, complete the returned billing step
  • After billing is active, retry the same request

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 Get API Access