audiopod-ai Reader API

openapi: 3.2.0
info:
  title: AudioPod AI Reader API
  description: '# AudioPod AI APIs


    ## Overview


    The AudioPod AI API provides advanced audio processing, AI-powered music generation, voice cloning, transcription, and audio publishing services over a versioned REST interface, with API-key authentication, typed error responses, and published rate limits. ## Base URL

    ```

    https://api.audiopod.ai/api/v1

    ```


    ## Authentication


    ### API Key Authentication (Recommended)

    Most API endpoints use API key authentication. Include your key in the header:

    ```

    X-API-Key: ap_your_api_key

    ```


    ### JWT Token Authentication

    For session-based access (web applications), obtain a token via `/auth/token`:

    ```

    Authorization: Bearer

    ```


    ### Public Endpoints

    Some endpoints like newsletter subscription, health checks, and shared content don''t require authentication. ## Versioning & Deprecation Policy


    The API is versioned **in the URL path**. The current version is `v1`, served at

    `https://api.audiopod.ai/api/v1`. Integrate against an explicit version — never

    against an unversioned path. - **Additive changes ship in place.** New endpoints, new optional request

    fields, and new response fields can appear in `v1` at any time. Clients must

    ignore unknown response fields rather than failing on them. - **Breaking changes ship as a new path version** (`/api/v2`). A breaking change

    is: removing or renaming a field or endpoint, changing a field''s type, adding a

    required request field, or changing the meaning of an existing value. - **Retirement is announced on the wire.** When an endpoint or version is

    scheduled for removal, its responses carry:

    - `Deprecation: true` — the endpoint is deprecated as of now. - `Sunset: ` — the date after which it stops responding

    (RFC 8594). - `Link: ; rel="successor-version"` — where to migrate to. - **Minimum notice: 6 months** between the first `Sunset` header and removal, for

    any endpoint outside a `dev`/preview tag. - Deprecated operations are also marked `"deprecated": true` in this

    specification, so a generated client can surface the warning at build time. ## Rate Limiting


    Limits are applied per API key (falling back to client IP for unauthenticated

    requests) and **scale with subscription tier** — higher tiers get proportionally

    more headroom on the same routes. Indicative baselines for the free tier:


    - **Standard**: 100 requests/minute

    - **Auth endpoints**: 10 requests/minute

    - **Upload endpoints**: 20 requests/minute

    - **Music generation**: `50/minute`

    - **Music retake**: `10/minute`

    - **Music repaint / extend / edit**: `3/minute`


    Do not hard-code these numbers. **Read the quota off the response headers**,

    which are returned on every rate-limited route (routes with no explicit limit

    send no quota headers — absence means "not throttled here", not "quota

    exhausted"):


    | Header | Meaning |

    |---|---|

    | `RateLimit-Limit` | Requests allowed in the current window |

    | `RateLimit-Remaining` | Requests still available in the current window |

    | `RateLimit-Reset` | Seconds until the window resets |

    | `RateLimit-Policy` | The quota policy, e.g. `100;w=60` |

    | `Retry-After` | On a `429` only: seconds to wait before retrying |


    The legacy `X-RateLimit-Limit` / `-Remaining` / `-Reset` names are still sent

    alongside the standard ones for older clients. On a `429`, back off for at least `Retry-After` seconds. Retries with

    exponential backoff and jitter are expected; tight retry loops are not. ## Errors


    Every `4xx` and `5xx` response uses one typed envelope:


    ```json

    {

    "error": "NOT_FOUND",

    "message": "The requested resource was not found.",

    "status": 404,

    "detail": "..."

    }

    ```


    - `error` — a **stable, machine-readable code**. Branch on this. - `message` — human-readable prose. Do not parse; wording can change. - `status` — the HTTP status, repeated for convenience. - `detail` — the legacy payload, retained for backward compatibility. For a

    `422` it is the array of failing fields. The full shape is published as the `ErrorResponse` schema, and each operation

    below documents the statuses it can return.'
  version: 2.0.0
servers:
- url: https://api.audiopod.ai
  description: Production
security:
- apiKeyAuth: []
- bearerAuth: []
tags:
- name: Reader
paths:
  /api/v1/reader/generate:
    post:
      tags:
      - Reader
      summary: Create Reader Job
      description: Create a new reader job for article-to-audio conversion
      operationId: create_reader_job
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReaderGenerateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReaderJobResponse'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-original-operation-id: create_reader_job_api_v1_reader_generate_post
  /api/v1/reader/estimate:
    post:
      tags:
      - Reader
      summary: Estimate Reader Job
      description: 'Estimate the credit cost of a reader job before generating it.


        Free voices cost nothing. For premium or custom voices the article is

        fetched up front — the same path generation uses — so the number returned

        here matches what is reserved and billed. If the article cannot be

        fetched, a baseline estimate is returned with `measured=false` rather than

        an error.'
      operationId: estimate_reader_job
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReaderEstimateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReaderEstimateResponse'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-original-operation-id: estimate_reader_job_api_v1_reader_estimate_post
  /api/v1/reader/public/{job_id}:
    get:
      tags:
      - Reader
      summary: Get Public Reader Job
      description: 'Public, unauthenticated reader job for the hosted share/embed page.


        Only completed, public jobs are returned.'
      operationId: get_public_reader_job
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: integer
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReaderPublicResponse'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-original-operation-id: get_public_reader_job_api_v1_reader_public__job_id__get
  /api/v1/reader/{job_id}:
    get:
      tags:
      - Reader
      summary: Get Reader Job
      description: Get reader job status
      operationId: get_reader_job
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: integer
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReaderJobResponse'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-original-operation-id: get_reader_job_api_v1_reader__job_id__get
    delete:
      tags:
      - Reader
      summary: Delete Reader Job
      description: Delete a reader job
      operationId: delete_reader_job
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: integer
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-original-operation-id: delete_reader_job_api_v1_reader__job_id__delete
  /api/v1/reader/:
    get:
      tags:
      - Reader
      summary: List Reader Jobs
      description: List user's reader jobs
      operationId: list_reader_jobs
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Page Size
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReaderJobsResponse'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-original-operation-id: list_reader_jobs_api_v1_reader__get
components:
  headers:
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    RateLimitLimit:
      description: Request quota for the current window on this route.
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests remaining in the current window.
      schema:
        type: integer
    RateLimitReset:
      description: Seconds until the current window resets.
      schema:
        type: integer
    RateLimitPolicy:
      description: Quota policy for this route, e.g. `100;w=60`. Limits scale with subscription tier.
      schema:
        type: string
  responses:
    BadRequest:
      description: Bad request — malformed syntax or an invalid parameter combination.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentRequired:
      description: 'Not enough credits to run this job. `detail` carries the typed InsufficientCreditsDetail object: what the job costs, what the account holds, and how to add more.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InsufficientCreditsResponse'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Authenticated, but not permitted (wrong scope, or a plan-gated feature).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationFailed:
      description: Request validation failed. `detail` lists the offending fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: Temporarily unavailable. Safe to retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required or the supplied credential is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded. Honour `Retry-After` before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
    NotFound:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: Conflict with the current state of the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ReaderEstimateResponse:
      properties:
        is_premium:
          type: boolean
          title: Is Premium
        estimated_credits:
          type: integer
          title: Estimated Credits
        word_count:
          type: integer
          title: Word Count
        char_count:
          type: integer
          title: Char Count
        measured:
          type: boolean
          title: Measured
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
      type: object
      required:
      - is_premium
      - estimated_credits
      - word_count
      - char_count
      - measured
      title: ReaderEstimateResponse
      description: 'Cost preview for the Audio Reader.


        `is_premium=false` means a free voice and zero cost. `measured=false`

        means the article could not be fetched in advance, so

        `estimated_credits` is a baseline and billing follows the actual length.'
    ReaderEstimateRequest:
      properties:
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        content:
          anyOf:
          - type: string
          - type: 'null'
          title: Content
        voice:
          type: string
          title: Voice
          default: aura-asteria-en
      type: object
      title: ReaderEstimateRequest
    InsufficientCreditsDetail:
      type: object
      title: InsufficientCreditsDetail
      description: 'Everything needed to resolve a credit shortfall: what the job costs, what the account holds, and the ways to add more.'
      properties:
        error:
          type: string
          description: Always `INSUFFICIENT_CREDITS` on this response.
          examples:
          - INSUFFICIENT_CREDITS
        message:
          type: string
          description: Human-readable explanation. Do not parse.
        credits_required:
          type:
          - integer
          - 'null'
          description: Credits this job needs. Null when the shortfall was detected without a priced estimate — show no figure rather than a wrong one.
        credits_available:
          type: integer
          description: 'Total spendable credits: subscription plus pay-as-you-go.'
        subscription_credits:
          type: integer
          description: Plan credits remaining in the current cycle.
        payg_credits:
          type: integer
          description: Pay-as-you-go credits, which never expire.
        current_plan:
          type: string
          examples:
          - Basic
        upgrade_options:
          type: array
          description: Plans above the current one, cheapest first.
          items:
            type: object
            properties:
              plan:
                type: string
              price:
                type: string
              credits:
                type: string
              annual:
                type: string
        payg_option:
          type: object
          description: Where to buy credits that never expire.
          properties:
            description:
              type: string
            url:
              type: string
        upgrade_url:
          type: string
          examples:
          - /pricing
        auto_refill:
          type: object
          description: Whether an automatic top-up is handling this shortfall. `off` means none is running and the caller should top up or upgrade; `pending` means one is in flight, so poll the balance and retry the same request; `failed` means one was attempted and did not complete; `ineligible` means automatic top-up cannot run for this account.
          properties:
            state:
              type: string
              enum:
              - 'off'
              - pending
              - failed
              - ineligible
          required:
          - state
        upload_ref:
          type:
          - string
          - 'null'
          description: Reference to the input already uploaded for this request, when there was one, so a retry after topping up does not have to send the file again. Null when the request carried no upload.
      required:
      - error
      - message
      - credits_available
      - current_plan
    InsufficientCreditsResponse:
      type: object
      title: InsufficientCreditsResponse
      description: Error envelope for a credit shortfall. Identical to ErrorResponse except that `detail` is the typed InsufficientCreditsDetail object.
      properties:
        code:
          type: string
          description: Stable machine-readable code. **Branch on this field.**
          examples:
          - PAYMENT_REQUIRED
        error:
          type: string
          examples:
          - PAYMENT_REQUIRED
        message:
          type: string
          description: Human-readable explanation. Do not parse.
        status:
          type: integer
          examples:
          - 402
        detail:
          $ref: '#/components/schemas/InsufficientCreditsDetail'
      required:
      - code
      - message
      - status
    ReaderPublicResponse:
      properties:
        id:
          type: integer
          title: Id
        status:
          type: string
          title: Status
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        audio_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Audio Url
        audio_duration_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Audio Duration Seconds
        show_branding:
          type: boolean
          title: Show Branding
          default: true
      type: object
      required:
      - id
      - status
      title: ReaderPublicResponse
      description: 'Unauthenticated view for the hosted share/embed page (audiopod.ai/r/{id}).


        Deliberately minimal — never leaks user, provider/model, source URL, raw

        content, parameters, or error internals. The audio is already at a public R2

        URL, so this exposes nothing the share link doesn''t already imply.'
    ErrorResponse:
      type: object
      title: ErrorResponse
      description: Standard error envelope. Every 4xx and 5xx response from the AudioPod AI API carries `code`, `message` and `status`. Branch on `code` — a stable machine-readable string — rather than parsing `message`, which is human-facing prose and may be reworded at any time. `detail` and `error` are retained for backward compatibility with older integrations, and their shapes vary by endpoint.
      properties:
        code:
          type: string
          description: Stable machine-readable error code, present on every error response. **Branch on this field.** Values are additive and existing codes are not renamed.
          examples:
          - NOT_FOUND
          - AUTHENTICATION_REQUIRED
          - RATE_LIMIT_EXCEEDED
        error:
          description: Legacy error field. Usually the same string as `code`, but a few older endpoints emit an object here instead (`code` / `message` / `details`). Prefer `code`, which is always a string.
          examples:
          - NOT_FOUND
          - AUTHENTICATION_REQUIRED
        message:
          type: string
          description: Human-readable explanation. Do not parse.
          examples:
          - The requested resource was not found.
        status:
          type: integer
          description: HTTP status code, repeated in the body for convenience.
          examples:
          - 404
        detail:
          description: Legacy detail payload, preserved verbatim for backward compatibility. A string for most errors, an array of field errors for validation failures, an object for auth failures.
      required:
      - code
      - message
      - status
    ReaderGenerateRequest:
      properties:
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        content:
          anyOf:
          - type: string
            maxLength: 300000
          - type: 'null'
          title: Content
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        voice:
          type: string
          title: Voice
          default: aura-asteria-en
        webhook_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Webhook Url
        show_branding:
          type: boolean
          title: Show Branding
          default: true
        template_slug:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Template Slug
      type: object
      title: ReaderGenerateRequest
    ReaderJobsResponse:
      properties:
        jobs:
          items:
            $ref: '#/components/schemas/ReaderJobResponse'
          type: array
          title: Jobs
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        page_size:
          type: integer
          title: Page Size
      type: object
      required:
      - jobs
      - total
      - page
      - page_size
      title: ReaderJobsResponse
    ReaderJobResponse:
      properties:
        id:
          type: integer
          title: Id
        status:
          type: string
          title: Status
        progress:
          type: number
          title: Progress
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        word_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Word Count
        audio_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Audio Url
        embed_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Embed Url
        embed_html:
          anyOf:
          - type: string
          - type: 'null'
          title: Embed Html
        audio_duration_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Audio Duration Seconds
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        created_at:
          type: string
          format: date-time
          title: Created At
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
        chunks_total:
          anyOf:
          - type: integer
          - type: 'null'
          title: Chunks Total
        chunks_skipped:
          anyOf:
          - type: integer
          - type: 'null'
          title: Chunks Skipped
        content_omitted:
          type: boolean
          title: Content Omitted
          default: false
      type: object
      required:
      - id
      - status
      - progress
      - created_at
      title: ReaderJobResponse
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /api/v1/auth/token
    OptionalOAuth2Scheme:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /api/v1/auth/token
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'AudioPod API key. Create one in the dashboard under API Keys and send it as `X-API-Key: ap_...`. This is the recommended method for server-to-server and agent integrations.'
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Session token obtained from `/api/v1/auth/token`. Intended for first-party web sessions; prefer an API key for integrations.