audiopod-ai Midi API

openapi: 3.2.0
info:
  title: AudioPod AI Midi 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: midi
paths:
  /api/v1/midi/convert:
    post:
      tags:
      - midi
      summary: Create Midi Conversion
      description: 'Standalone audio-to-MIDI: upload a file or pass a URL; we split it into

        stems and transcribe each pitched stem, returning per-stem + multitrack MIDI

        (and the separated stem audio).'
      operationId: create_midi_conversion
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_create_midi_conversion_api_v1_midi_convert_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MidiConversionJobResponse'
        '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_midi_conversion_api_v1_midi_convert_post
  /api/v1/midi/convert/from-stems/{stem_job_id}:
    post:
      tags:
      - midi
      summary: Create Midi From Stems
      description: 'Add-on: transcribe the already-separated stems of a completed stem-extraction

        job. Bills the add-on rate only (no re-split).'
      operationId: create_midi_from_stems
      parameters:
      - name: stem_job_id
        in: path
        required: true
        schema:
          type: integer
          title: Stem Job Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MidiFromStemsRequest'
              default: {}
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MidiConversionJobResponse'
        '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_midi_from_stems_api_v1_midi_convert_from_stems__stem_job_id__post
  /api/v1/midi/status/{job_id}:
    get:
      tags:
      - midi
      summary: Get Midi Status
      operationId: get_midi_status
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          anyOf:
          - type: integer
          - type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MidiConversionJobResponse'
        '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_midi_status_api_v1_midi_status__job_id__get
  /api/v1/midi/jobs:
    get:
      tags:
      - midi
      summary: List Midi Jobs
      operationId: list_midi_jobs
      parameters:
      - name: skip
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Skip
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MidiConversionJobResponse'
                title: Response List Midi Jobs Api V1 Midi Jobs Get
        '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_midi_jobs_api_v1_midi_jobs_get
  /api/v1/midi/jobs/{job_id}:
    delete:
      tags:
      - midi
      summary: Delete Midi Job
      operationId: delete_midi_job
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          anyOf:
          - type: integer
          - type: string
          title: Job Id
      responses:
        '204':
          description: Successful Response
        '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_midi_job_api_v1_midi_jobs__job_id__delete
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'
    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'
    ValidationFailed:
      description: Request validation failed. `detail` lists the offending fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    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
    MidiConvertOptions:
      properties:
        onset_threshold:
          type: number
          maximum: 0.95
          minimum: 0.05
          title: Onset Threshold
          default: 0.5
        frame_threshold:
          type: number
          maximum: 0.95
          minimum: 0.05
          title: Frame Threshold
          default: 0.3
        min_note_len_ms:
          type: number
          maximum: 2000.0
          minimum: 10.0
          title: Min Note Len Ms
          default: 128.0
        tempo_bpm:
          anyOf:
          - type: number
            maximum: 300.0
            minimum: 30.0
          - type: 'null'
          title: Tempo Bpm
        engine:
          type: string
          enum:
          - general
          - piano
          - vocal
          title: Engine
          default: general
      type: object
      title: MidiConvertOptions
      description: 'Tunables forwarded to the audio-to-MIDI engine. Thresholds override the

        per-stem presets; the bass octave-correction is always-on and not exposed.'
    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
    Body_create_midi_conversion_api_v1_midi_convert_post:
      properties:
        file:
          anyOf:
          - type: string
            format: binary
          - type: 'null'
          title: File
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        stems:
          anyOf:
          - type: string
          - type: 'null'
          title: Stems
        options:
          anyOf:
          - type: string
          - type: 'null'
          title: Options
      type: object
      title: Body_create_midi_conversion_api_v1_midi_convert_post
    ProcessingStatus:
      type: string
      enum:
      - PENDING
      - PROCESSING
      - COMPLETED
      - FAILED
      - CANCELLED
      title: ProcessingStatus
    MidiFromStemsRequest:
      properties:
        stems:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Stems
        options:
          anyOf:
          - $ref: '#/components/schemas/MidiConvertOptions'
          - type: 'null'
      type: object
      title: MidiFromStemsRequest
    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
    MidiConversionJobResponse:
      properties:
        id:
          type: integer
          title: Id
        status:
          $ref: '#/components/schemas/ProcessingStatus'
        progress:
          anyOf:
          - type: number
          - type: 'null'
          title: Progress
          description: Progress percentage (0-100)
        stage:
          anyOf:
          - type: string
          - type: 'null'
          title: Stage
          description: '"split" | "transcribe" | "merge"'
        mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Mode
          description: '"standalone" | "from_stem_job"'
        source_job_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Source Job Id
        stems_requested:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Stems Requested
        midi_urls:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Midi Urls
        merged_midi_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Merged Midi Url
        stem_urls:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Stem Urls
        detected_tempo_bpm:
          anyOf:
          - type: number
          - type: 'null'
          title: Detected Tempo Bpm
        skipped_stems:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Skipped Stems
        failed_stems:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Failed Stems
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        duration:
          anyOf:
          - type: number
          - type: 'null'
          title: Duration
        original_filename:
          anyOf:
          - type: string
          - type: 'null'
          title: Original Filename
        created_at:
          type: string
          format: date-time
          title: Created At
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
      type: object
      required:
      - id
      - status
      - created_at
      title: MidiConversionJobResponse
      description: Status/response model for a MIDI conversion job (frozen contract).
  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.