Audio Delivery Network Cover Images API

openapi: 3.2.0
info:
  title: AudioDN Cover Images API
  version: 1.0.0
  summary: 'Audio delivery infrastructure: upload, transcode, secure delivery, and playback.'
  description: 'AudioDN provides a REST API and embeddable web components for managing and delivering audio at scale.


    Authentication: bearer token via the `Authorization` header. Use a server-side API key for full access; mint scoped client-side keys (Player or Uploader) for browsers and mobile apps.


    All endpoints are prefixed with `/v1/`.'
  contact:
    name: Audio Delivery Network
    email: support@audiodeliverynetwork.com
    url: https://audiodeliverynetwork.com
  license:
    name: Proprietary
servers:
- url: https://api.audiodelivery.net
  description: Production
security:
- BearerAuth: []
tags:
- name: Cover Images
paths:
  /v1/collection/{collection_id}/cover:
    post:
      tags:
      - Cover Images
      operationId: createCollectionCover
      summary: Generate a collection cover image upload URL
      parameters:
      - name: collection_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Upload handle.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    collection_id:
                      type: string
                      format: uuid
                    collection:
                      $ref: '#/components/schemas/Collection'
                    collection_cover_upload:
                      $ref: '#/components/schemas/UploadHandle'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/track/{track_id}/cover:
    post:
      tags:
      - Cover Images
      operationId: createTrackCover
      summary: Generate a track cover image upload URL
      parameters:
      - name: track_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Upload handle.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OkEnvelope'
                - type: object
                  properties:
                    track_id:
                      type: string
                      format: uuid
                    track:
                      $ref: '#/components/schemas/Track'
                    track_cover_upload:
                      $ref: '#/components/schemas/UploadHandle'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ImageColor:
      type: object
      properties:
        hex:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        area:
          type: number
        lightness:
          type: number
        saturation:
          type: number
    Track:
      type: object
      properties:
        id:
          type: string
          format: uuid
        collection_id:
          type: string
          format: uuid
        creator_id:
          type: string
          format: uuid
        file_name:
          type: string
        duration:
          type: number
        organization_index:
          type: string
        metadata:
          type: object
          additionalProperties: true
        is_cover_overridable:
          type: boolean
        is_theme_overridable:
          type: boolean
        player_title:
          type: string
        player_subtitle:
          type: string
        player_color:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        player_color_light:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          readOnly: true
          description: Derived read-only variant of player_color adjusted to stay legible on a light background.
        player_color_dark:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          readOnly: true
          description: Derived read-only variant of player_color adjusted to stay legible on a dark background.
        transcription:
          type:
          - string
          - 'null'
          readOnly: true
          description: Plain-text transcription as paragraphs when transcription is enabled for the organization. Null when unavailable. Language is auto-detected unless provisioned otherwise. Transcription is not a self-serve / selectable variant — contact AudioDN if you need it.
        transcription_language:
          type:
          - string
          - 'null'
          readOnly: true
          description: BCP-47 language code of the spoken source language for `transcription` (from automatic language detection, or a provisioned language override). Null when unavailable.
        status:
          type: string
          enum:
          - initializing
          - processing
          - fallback_processing
          - ready
          - incomplete
          - failed
        base_path:
          type: string
          readOnly: true
          description: Durable delivery path prefix for this track's variant files. Each variant file is base_path plus its variant suffix and extension (e.g. `{base_path}_preview.mp3`).
        base_url:
          type: string
          format: uri
          readOnly: true
          description: 'Durable delivery URL prefix: base_path served from the organization''s unique audiodelivery.net subdomain. Append the variant suffix and extension, then sign for delivery (e.g. `{base_url}_128.mp3`).'
    Error:
      type: object
      required:
      - ok
      - message
      properties:
        ok:
          type: boolean
          const: false
        message:
          type: string
        api_request_id:
          type: string
          format: uuid
    OkEnvelope:
      type: object
      required:
      - ok
      - api_request_id
      properties:
        ok:
          type: boolean
          const: true
        api_request_id:
          type: string
          format: uuid
    Collection:
      type: object
      properties:
        id:
          type: string
          format: uuid
        creator_id:
          type: string
          format: uuid
        organization_index:
          type: string
        title:
          type: string
        metadata:
          type: object
          additionalProperties: true
        theme:
          type: array
          items:
            $ref: '#/components/schemas/ImageColor'
        is_cover_overridable:
          type: boolean
        is_theme_overridable:
          type: boolean
        player_color:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        player_color_light:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          readOnly: true
          description: Derived read-only variant of player_color adjusted to stay legible on a light background.
        player_color_dark:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          readOnly: true
          description: Derived read-only variant of player_color adjusted to stay legible on a dark background.
        player_subtitle:
          type: string
    UploadHandle:
      type: object
      properties:
        method:
          type: string
          enum:
          - PUT
          - POST
        upload_url:
          type: string
          format: uri
        ttl:
          type: integer
        expires_at:
          type: string
          format: date-time
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Server-side API key. Use scoped client-side keys for browser and mobile contexts.