Start with Lector API

Get your API key

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

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

BASE="https://api.lectorai.app"

curl -sS "$BASE/v1/tts" \
    -H "Authorization: Bearer $LECTOR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "text": "Your weekly report is ready."
    }'

tts_provider and voice are optional. If omitted, Lector currently uses OpenAI and the nova voice.

Defaults and explicit control

• tts_provider is optional. When omitted, OpenAI is used.
• voice is optional. The current default voice is nova.
• format defaults to mp3.
• When delivery is omitted, it defaults to url. Explicit delivery: "auto" is a deliberate request and is not the same as omission.

Specify a provider and voice

curl -sS "$BASE/v1/tts" \
  -H "Authorization: Bearer $LECTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome. Your room is ready.",
    "tts_provider": "xai",
    "voice": "eve",
    "format": "mp3",
    "delivery": "url"
  }'

Use the defaults when convenience matters. Be explicit when provider, voice, format, or delivery is part of the product experience.

Choose a voice provider

Lector can route text-to-audio requests through supported voice providers. If tts_provider is omitted, Lector uses OpenAI.

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"
        }'

Format behavior and fallback

Lector accepts MP3 and WAV requests across its current voice providers, but the generation path can vary by provider:

• OpenAI: MP3 and WAV are generated directly.
• xAI: Lector accepts MP3 and WAV requests.
• Gemini: WAV is generated natively. Short-to-medium MP3 requests are handled through Lector's audio conversion layer, while longer requests may use OpenAI as a quality-preserving fallback.

Provider integrations can evolve. Authenticated applications and agents should inspect /v1/capabilities for the current providers, voices, formats, delivery modes, fallback policies, plan access, and endpoint support. Applications and agents should handle runtime validation and inspect response metadata to confirm the provider, fallback, generation path, and conversion used for each request.

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 to turn image-based content into audio.

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.

Stream

The response body contains binary audio, while metadata is returned through response headers. Save the headers separately from the audio. Do not use curl -i with --output audio.mp3 or --output audio.wav because the headers could be written into the audio file.

curl -sS "$BASE/v1/tts" \
  -H "Authorization: Bearer $LECTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your delivery has arrived.",
    "tts_provider": "openai",
    "voice": "nova",
    "format": "mp3",
    "delivery": "stream"
  }' \
  -D headers.txt \
  --output delivery.mp3

delivery.mp3 contains the audio. headers.txt contains the HTTP and Lector metadata headers.

Hosted URL

delivery: "url" completes generation and returns JSON containing audio_url and output.url. The URL is temporary and signed. Applications and agents can pass it to another system, retain it temporarily, share it, or play it later.

curl -sS "$BASE/v1/tts" \
  -H "Authorization: Bearer $LECTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The approved update is ready to publish.",
    "tts_provider": "openai",
    "voice": "nova",
    "format": "mp3",
    "delivery": "url"
  }' \
  -D headers.txt \
  --output response.json

Asynchronous URL

delivery: "async_url" creates a durable, worker-backed job. The initial response is 202 Accepted and includes job_id and status_url, but not the completed audio URL. Check /v1/jobs/{job_id} until the job reaches completed or failed.

curl -sS -X POST "$BASE/v1/listen-content" \
  -H "Authorization: Bearer $LECTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -D async-headers.txt \
  --output async-response.json \
  -d '{
    "content": "Approved operations update: the east entrance will close at 8:00 PM. Direct visitors to the north entrance after that time.",
    "source_type": "operations_update",
    "tts_provider": "openai",
    "voice": "nova",
    "format": "mp3",
    "delivery": "async_url"
  }'

curl -sS "$BASE/v1/jobs/JOB_ID" \
  -H "Authorization: Bearer $LECTOR_API_KEY"

• 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
• Important: /v1/listen-url does not currently support async_url.

Auto

delivery: "auto" allows Lector to resolve the current delivery mode for the endpoint. Auto affects delivery only. Explicit provider, voice, speed, format, pages, reading order, extraction mode, and other settings remain unchanged.

curl -sS -X POST "$BASE/v1/listen-document-url" \
  -H "Authorization: Bearer $LECTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -D auto-headers.txt \
  --output auto-response.json \
  -d '{
    "url": "https://example.com/report.pdf",
    "tts_provider": "openai",
    "voice": "nova",
    "format": "mp3",
    "delivery": "auto",
    "extraction_mode": "auto",
    "reading_order": "ltr"
  }'

Current delivery: "auto" 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

Auto changes delivery only. It does not change tts_provider, voice, format, speed, pages, reading_order, extraction_mode, or other explicit options. Omitting delivery defaults to url; it does not invoke auto resolution.

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 -sS "$BASE/v1/capabilities" \
  -H "Authorization: Bearer $LECTOR_API_KEY"

Understand the response

Lector returns audio together with structured information applications and agents can use. URL responses can include:

• Request ID, requested provider, provider used, provider fallback, and selected voice
• Detected language, reading direction, delivery method, and audio format
• Characters used, duration and playback information, source type and subtype
• Document information where relevant, hosted audio URL, and generation or conversion details where applicable

Stream response headers

For stream delivery, much of this information is returned through HTTP headers:

X-Request-Id
X-Characters-Used
X-Duration-Seconds
X-Voice
X-TTS-Provider
X-Requested-TTS-Provider
X-TTS-Fallback
X-Format
X-Delivery
X-Detected-Language
X-Detected-Direction

A human-facing application can display or store those details. An agent can use them to verify the result, record usage, deliver the audio, save the URL, or decide what should happen next.

Async job responses

The initial 202 response describes the queued request. audio_url is not available until the job completes. The completed job response includes the audio URL and relevant provider, fallback, usage, source, delivery, and job information.

Supported content and current limits

• Maximum submitted or extracted content: 20,000 characters per request
• Maximum document or image upload/fetch size: 10 MiB
• Supported documents: PDF, DOCX, TXT, Markdown (.md), and Rich Text Format (.rtf)
• Supported images: JPEG and JPG, PNG, WebP (.webp), and GIF

Content quality can vary depending on the source. Low-resolution images, stylized text, dense layouts, and unusual document structures may produce imperfect narration.

For medical, legal, financial, safety-related, or other high-stakes content, users should verify the audio against the original source.

Public URL access

Public webpages, images, and document links must be accessible without a login for Lector to retrieve them. Lector does not bypass authentication, private access controls, or paywalls. A share-link format does not guarantee that the content is anonymously retrievable.

For private dashboards, inboxes, authenticated pages, or content an application or agent already has access to, send the content directly through /v1/tts or /v1/listen-content.

Google Docs example

curl -sS "$BASE/v1/listen-document-url" \
  -H "Authorization: Bearer $LECTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.google.com/document/d/DOCUMENT_ID/edit?usp=sharing",
    "tts_provider": "openai",
    "voice": "nova",
    "format": "mp3",
    "delivery": "url",
    "extraction_mode": "auto",
    "reading_order": "ltr"
  }'

Lector normalizes supported Google Docs links to an exportable document URL. The document must still allow anonymous viewing and export; the share-link format alone does not guarantee access. Google Drive viewer normalization works only when the file is publicly downloadable.

One workflow for applications and agents

A developer can configure Lector inside a product. An agent can inspect /v1/capabilities, choose the appropriate endpoint, request a provider and voice, select a delivery mode, and use the returned information to continue the workflow. Both use the same API surface.

curl -sS "$BASE/v1/listen-content" \
  -H "Authorization: Bearer $LECTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Approved operations update: the east entrance will close at 8:00 PM. Direct visitors to the north entrance after that time.",
    "source_type": "agent_report",
    "tts_provider": "openai",
    "voice": "nova",
    "speed": 1.0,
    "format": "mp3",
    "delivery": "async_url"
  }'

curl -sS "$BASE/v1/jobs/JOB_ID" \
  -H "Authorization: Bearer $LECTOR_API_KEY"

When the job completes, the response includes the hosted audio URL together with provider, fallback, usage, source, delivery, and job information the agent can use for its next action.

Choose the input. Choose how specific the request should be. Choose how the audio should return.

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.

Authenticated applications and agents can call /v1/billing/status to inspect their subscription, monthly usage, limits, and API-key state.

• Use a Lector API key to authenticate requests.
• Call /v1/billing/status to check the active plan, subscription, usage, limits, and API-key state.
• If Lector returns payment_required, complete the billing step included in the response.
• Retry the original request after API access becomes active.

Billing status example

curl -sS "$BASE/v1/billing/status" \
  -H "Authorization: Bearer $LECTOR_API_KEY"

The response is authenticated and account-specific. It may include account information, Stripe identifiers, and API-key details. Avoid exposing or logging the complete response in client-facing applications.

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?