Crevio Audio API

openapi: 3.2.0
info:
  title: Crevio API V1 Audio API
  version: 1.0.0
  description: 'API for the Crevio creator platform — a multi-tenant SaaS for digital product sales.

    Uses snake_case keys following Stripe conventions. All resource IDs are string IDs (e.g., "prod_abc123").


    Authentication is a bearer token: `Authorization: Bearer $CREVIO_API_KEY`.

    List endpoints are cursor-paginated with `limit` and `starting_after`.

    Writes accept an `Idempotency-Key` header and are safe to retry.


    Every response carries IETF RateLimit headers (`RateLimit`, `RateLimit-Policy`) so a client can

    self-throttle, and `Retry-After` on a 429. The quota is 600 requests per minute per credential.


    The API is versioned in the URL path (`/v1`). Nothing is removed without in-band warning: a

    deprecated operation is marked `"deprecated": true` here and serves `Deprecation` (RFC 9745),

    `Sunset` (RFC 8594) and `Link; rel="deprecation"` headers for at least six months before it

    stops answering. See https://crevio.co/docs/developer/guides/versioning.'
  contact:
    email: support@crevio.co
    name: Crevio Support
    url: https://crevio.co/docs
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://crevio.co/legal/terms-of-service
servers:
- url: https://api.crevio.co/v1
  description: Production
security:
- ApiKey: []
tags:
- name: Audio
  description: AI audio generation
paths:
  /audio/generate:
    post:
      summary: Generate audio
      description: Submits an asynchronous audio (text-to-speech) generation job to the fal.ai queue and returns the queued job immediately. It speaks the given text; for a song, soundtrack or instrumental use `POST /v1/audio/music`. Poll `GET /v1/jobs/{id}` or `GET /v1/audio/{id}` for status and results. Credits are charged only when the job completes successfully.
      operationId: generateAudio
      x-crevio-sdk-method: generate
      tags:
      - Audio
      security:
      - ApiKey: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Makes this write safe to retry: a repeat with the same key replays the first response instead of creating a second resource. Scoped to the account, remembered for 24 hours; reusing a key with a different payload is an error.'
        schema:
          type: string
          maxLength: 255
        example: 1f7a4c2e-3b19-4a6d-9f0c-2ac81b5d7e33
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudioGenerateRequest'
      responses:
        '202':
          description: Generation job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.audio.generate({\n    input: {\n      text: \"<value>\",\n    },\n  });\n\n  console.log(result);\n}\n\nrun();"
  /audio/models:
    get:
      summary: List audio models
      description: Lists the audio (text-to-speech) generation models available to `POST /v1/audio/generate`, enriched with live fal.ai pricing.
      operationId: listAudioModels
      x-crevio-sdk-method: listModels
      tags:
      - Audio
      security:
      - ApiKey: []
      responses:
        '200':
          description: List of audio models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse_GenerationModel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.audio.listModels();\n\n  console.log(result);\n}\n\nrun();"
  /audio/music:
    post:
      summary: Generate music
      description: Submits an asynchronous music generation job (an original song or instrumental track from a text description) to the fal.ai queue and returns the queued job immediately. Use it for soundtracks, background beds, jingles and intros; for spoken words use `POST /v1/audio/generate`. Poll `GET /v1/jobs/{id}` or `GET /v1/audio/{id}` for status; the finished track is `result.audio`. Credits are charged only when the job completes successfully.
      operationId: generateMusic
      x-crevio-sdk-method: generateMusic
      tags:
      - Audio
      security:
      - ApiKey: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Makes this write safe to retry: a repeat with the same key replays the first response instead of creating a second resource. Scoped to the account, remembered for 24 hours; reusing a key with a different payload is an error.'
        schema:
          type: string
          maxLength: 255
        example: 1f7a4c2e-3b19-4a6d-9f0c-2ac81b5d7e33
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MusicGenerateRequest'
      responses:
        '202':
          description: Generation job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.audio.generateMusic({\n    input: {\n      prompt: \"<value>\",\n    },\n  });\n\n  console.log(result);\n}\n\nrun();"
  /audio/music/models:
    get:
      summary: List music models
      description: Lists the music generation models available to `POST /v1/audio/music`, enriched with live fal.ai pricing.
      operationId: listMusicModels
      x-crevio-sdk-method: listMusicModels
      tags:
      - Audio
      security:
      - ApiKey: []
      responses:
        '200':
          description: List of music models
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse_GenerationModel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.audio.listMusicModels();\n\n  console.log(result);\n}\n\nrun();"
  /audio/{id}:
    get:
      summary: Get audio job
      description: Convenience alias for `GET /v1/jobs/{id}` that asserts the job is a speech or music generation job (404 otherwise).
      operationId: getAudioJob
      x-crevio-sdk-method: get
      tags:
      - Audio
      security:
      - ApiKey: []
      parameters:
      - name: id
        in: path
        required: true
        description: The resource ID (e.g., "prod_abc123") or slug (e.g., "my-product")
        schema:
          type: string
      responses:
        '200':
          description: Job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.audio.get({\n    id: \"<id>\",\n  });\n\n  console.log(result);\n}\n\nrun();"
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: forbidden
              message: You do not have permission to perform this action
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: bad_request
              message: The request was malformed or contained invalid parameters
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: authentication_required
              message: You did not provide an API key.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: resource_missing
              message: The requested resource was not found
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    TooManyRequests:
      description: 'Rate limit exceeded — 600 requests per minute per owner on the free tier: every API key and OAuth token one person holds on an account shares one budget, and the account''s team keys share another. Retry after the number of seconds in `Retry-After`.'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: rate_limit_exceeded
              message: Too many requests. Please retry later.
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: api_error
              code: internal_error
              message: An unexpected error occurred
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    UnprocessableEntity:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: validation_error
              code: validation_failed
              message: Email is required
              errors:
                email:
                - can't be blank
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
  schemas:
    AudioGenerateRequest:
      type: object
      properties:
        model:
          type: string
          examples:
          - fast
          - balanced
          - quality
          - fal-ai/inworld-tts
          - fal-ai/elevenlabs/tts/turbo-v2.5
          - alibaba/qwen-audio-3-tts
          - fal-ai/elevenlabs/tts/multilingual-v2
          - fal-ai/elevenlabs/tts/eleven-v3
          description: A quality tier (fast, balanced, quality) or any fal.ai text-to-speech endpoint id. Prefer a tier — it tracks the best current model for that price point. Defaults to fal-ai/elevenlabs/tts/multilingual-v2; `GET /v1/audio/models` maps tiers to ids with live pricing.
        input:
          type: object
          description: Model-specific input, forwarded to fal verbatim. `text` is required.
          properties:
            text:
              type: string
              description: The text to convert to speech.
            voice:
              type: string
              description: For the default model and the `balanced` tier (both ElevenLabs), one of Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill, or an ElevenLabs voice id. An unknown name silently falls back to the default voice (Rachel). Other models take their own voice names.
          required:
          - text
      required:
      - input
    GenerationModel:
      type: object
      properties:
        object:
          type: string
          enum:
          - model
        id:
          type: string
        tier:
          type:
          - string
          - 'null'
          enum:
          - fast
          - balanced
          - quality
          - null
          description: Quality tier this model backs. Pass the tier name as `model` instead of the id.
        default:
          type: boolean
        unit_price:
          type:
          - number
          - 'null'
        unit:
          type:
          - string
          - 'null'
        currency:
          type:
          - string
          - 'null'
        credits_per_second:
          type:
          - number
          - 'null'
          description: 'Video models only: Crevio credits per second of output, from what recent generations were billed.'
      required:
      - object
      - id
      - default
    ProviderJob:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        type:
          type: string
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          - cancelled
        model:
          type: string
        progress:
          type: integer
        input:
          type: object
        result:
          type:
          - object
          - 'null'
        error:
          type:
          - string
          - 'null'
        error_code:
          type:
          - string
          - 'null'
        credits_used:
          type:
          - integer
          - 'null'
        provider_request_id:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
        started_at:
          type:
          - string
          - 'null'
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - id
      - object
      - type
      - status
      - model
      - progress
      - input
      - result
      - error
      - error_code
      - credits_used
      - provider_request_id
      - created_at
      - started_at
      - completed_at
    ListResponse_GenerationModel:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/GenerationModel'
        has_more:
          type: boolean
        url:
          type: string
      required:
      - object
      - data
      - has_more
      - url
    MusicGenerateRequest:
      type: object
      properties:
        model:
          type: string
          examples:
          - fast
          - balanced
          - quality
          - minimax/music-3
          - fal-ai/lyria3/pro
          - mureka/api/generate/instrumental
          description: A quality tier (fast, balanced, quality) or any fal.ai text-to-music endpoint id. Prefer a tier — it tracks the best current model for that price point. Defaults to fal-ai/lyria3/pro; `GET /v1/audio/music/models` maps tiers to ids with live pricing.
        input:
          type: object
          description: Model-specific input, forwarded to fal verbatim. `prompt` is required. Tracks come back at the model's own length; trim and fade them to fit.
          properties:
            prompt:
              type: string
              description: 'The track to make: genre, mood, tempo (BPM), lead instruments, energy, and "instrumental, no vocals" for a background bed.'
            lyrics:
              type: string
              description: Lyrics to sing, for models that sing. Omit it for an instrumental.
            duration:
              type: number
              description: Upper bound on length in seconds, for models that take one (the `fast` tier).
          required:
          - prompt
      required:
      - input
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - api_error
              - invalid_request_error
              - validation_error
            code:
              type: string
            message:
              type: string
            param:
              type: string
            errors:
              type: object
            doc_url:
              type: string
          required:
          - type
          - message
      required:
      - error
  headers:
    Sunset:
      description: Present only on a deprecated operation. HTTP-date (RFC 8594) after which the operation stops responding. Always at least six months after `Deprecation`.
      schema:
        type: string
        examples:
        - Thu, 01 Oct 2026 00:00:00 GMT
    RequestId:
      description: Unique id for this request. Quote it when reporting a problem.
      schema:
        type: string
        examples:
        - 8fe045fe-cb8a-4407-a44d-5df60385e522
    DeprecationLink:
      description: Present only on a deprecated operation. `<url>; rel="deprecation"` pointing at the migration notes.
      schema:
        type: string
        examples:
        - <https://crevio.co/docs/developer/guides/versioning>; rel="deprecation"
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        examples:
        - 11
    Deprecation:
      description: Present only on a deprecated operation. Structured-field date (RFC 9745) — `@` followed by the Unix timestamp at which the operation became deprecated.
      schema:
        type: string
        examples:
        - '@1775001600'
    RateLimit:
      description: 'Remaining quota for the current window, as an IETF structured field: `"default";r=<remaining>;t=<seconds until reset>`.'
      schema:
        type: string
        examples:
        - '"default";r=596;t=11'
    RateLimitPolicy:
      description: 'The quota this credential is subject to: `"default";q=<requests>;w=<window seconds>`.'
      schema:
        type: string
        examples:
        - '"default";q=600;w=60'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key in the format: Bearer {api_token}'
externalDocs:
  description: Crevio developer documentation
  url: https://crevio.co/docs/developer
x-mint:
  mcp:
    enabled: true
x-api-lifecycle:
  current_major_version: v1
  versioning_scheme: URL path
  deprecation_policy_url: https://crevio.co/docs/developer/guides/versioning
  minimum_notice_days: 183
  deprecation_headers:
  - Deprecation
  - Sunset
  - Link