kymaapi-com Audio API

openapi: 3.2.0
info:
  title: Kymaapi Com Audio API
  version: 1.0.0
  contact:
    name: Kyma API
    url: https://kymaapi.com
    email: support@kymaapi.com
  license:
    name: Proprietary
  termsOfService: https://kymaapi.com/terms
  description: 'Operations tagged Audio across 2 of this provider''s published API definitions: kymaapi-com-openapi.json, kymaapi-com-v1-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://kymaapi.com/v1
  description: Production
security:
- BearerAuth: []
tags:
- name: Audio
paths:
  /audio/transcriptions:
    post:
      operationId: createAudioTranscription
      summary: Create audio transcription (sync)
      description: Speech-to-text. Multipart upload; sync response. OpenAI Whisper API compatible. Pass a SKU like `whisper-v3-turbo`. Billed per second, 10-second minimum per request.
      tags:
      - Audio
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Audio file (mp3, wav, m4a, ogg, webm, flac). Max 25 MB.
                model:
                  type: string
                  default: whisper-v3-turbo
                  description: A SKU like `whisper-v3-turbo`, `gpt-transcribe` or `gemini-3.5-transcribe`.
                language:
                  type: string
                  description: Optional ISO-639-1 code (e.g. `en`, `vi`). Whisper auto-detects when omitted.
                response_format:
                  type: string
                  enum:
                  - json
                  - verbose_json
                  - text
                  - srt
                  - vtt
                  default: verbose_json
                  description: json / verbose_json return JSON; text returns plain text; srt and vtt return subtitle files. Billing details ride X-Kyma-* response headers when the body is text/srt/vtt; they live in the JSON body for json/verbose_json.
                temperature:
                  type: number
                  minimum: 0
                  maximum: 1
                  default: 0
                prompt:
                  type: string
                  description: Optional priming text to nudge the model toward known proper nouns or domain vocabulary.
      responses:
        '200':
          description: Transcript in the requested response_format. JSON formats embed a billing block; text/srt/vtt expose billing via X-Kyma-* response headers so the body remains a plain transcript or subtitle file.
          headers:
            X-Kyma-Model:
              schema:
                type: string
              description: The Kyma model SKU that served the request.
            X-Kyma-Duration-Sec:
              schema:
                type: number
              description: Detected audio duration in seconds.
            X-Kyma-Billable-Minutes:
              schema:
                type: integer
              description: Minutes charged. Always >= 1.
            X-Kyma-Cost-USD:
              schema:
                type: number
              description: Final cost charged for this request.
            X-Kyma-Balance-USD:
              schema:
                type: number
              description: Remaining account balance after this charge.
          content:
            application/json:
              schema:
                oneOf:
                - description: response_format=json
                  type: object
                  properties:
                    text:
                      type: string
                    model:
                      type: string
                    billing:
                      $ref: '#/components/schemas/AudioBilling'
                - description: response_format=verbose_json (default)
                  type: object
                  properties:
                    task:
                      type: string
                    language:
                      type: string
                    duration:
                      type: number
                    text:
                      type: string
                    segments:
                      type: array
                      items:
                        type: object
                    model:
                      type: string
                    billing:
                      $ref: '#/components/schemas/AudioBilling'
            text/plain; charset=utf-8:
              schema:
                type: string
                description: response_format=text
            application/x-subrip; charset=utf-8:
              schema:
                type: string
                description: response_format=srt — SubRip subtitle file
            text/vtt; charset=utf-8:
              schema:
                type: string
                description: response_format=vtt — WebVTT subtitle file
        '400':
          description: Missing file, not multipart, or model not a transcription SKU
        '401':
          description: Missing or invalid API key
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: Audio gate not enabled on this account
        '413':
          description: Audio file exceeds 25 MB
        '502':
          description: Upstream transcription failed
    servers:
    - url: https://kymaapi.com/v1
      description: Production
  /audio/understand:
    post:
      operationId: createAudioUnderstand
      summary: Create audio understanding (sync)
      description: 'Retired 2026-10-08: no model is served on this endpoint. Its only model, also the default, was retired and the `audio-understand` alias removed; every request returns 404 model_not_found and nothing is charged. Was: audio scene Q&A (tone, music, SFX, language, speaker emotion), billed per minute, rounded up.'
      deprecated: true
      tags:
      - Audio
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - question
              properties:
                file:
                  type: string
                  format: binary
                  description: Audio file (mp3, wav, m4a, ogg, webm, flac). Max 25 MB inline.
                question:
                  type: string
                  description: Free-form question about the audio.
                model:
                  type: string
                  description: No model is served since 2026-10-08.
                duration_sec:
                  type: integer
                  description: Optional duration hint in seconds. When supplied, billing rounds up from this value. When omitted, Kyma estimates duration from file size.
      responses:
        '200':
          description: Free-form answer plus a Kyma billing block
          content:
            application/json:
              schema:
                type: object
                properties:
                  answer:
                    type: string
                  model:
                    type: string
                  billing:
                    $ref: '#/components/schemas/AudioBilling'
        '400':
          description: Missing file or question, or model not an audio-understanding SKU
        '401':
          description: Missing or invalid API key
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: Audio gate not enabled on this account
        '413':
          description: Audio file exceeds 25 MB
        '502':
          description: Upstream audio understanding failed
    servers:
    - url: https://kymaapi.com/v1
      description: Production
  /audio/speech:
    post:
      operationId: createSpeech
      summary: Text-to-speech (sync)
      description: Synthesize speech from text. Synchronous - returns the audio bytes directly. OpenAI /audio/speech compatible (input + voice). Billed per character (max 5000 chars/request). Pick a voice_id from GET /v1/audio/voices, or omit voice to use a provider default.
      tags:
      - Audio
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - input
              properties:
                model:
                  type: string
                  default: eleven-multilingual-v2
                  description: TTS model SKU (ElevenLabs or MiniMax family). Non-TTS models return 400 not_a_tts_model.
                input:
                  type: string
                  maxLength: 5000
                  description: 'Text to speak. Max 5000 characters (NFC-normalized) per request - split longer text client-side. Alias: text.'
                voice:
                  type: string
                  description: Voice id. OpenAI-style voice or provider voice_id both accepted. Defaults to a known-good voice per provider when omitted. List options via GET /v1/audio/voices.
                response_format:
                  type: string
                  default: mp3_44100_128
                  description: Output audio format. ElevenLabs uses names like mp3_44100_128; MiniMax accepts mp3/wav/flac/pcm. The first segment is used, so an OpenAI-style mp3_44100_128 maps to mp3 on MiniMax.
                speed:
                  type: number
                  description: MiniMax only. Playback speed multiplier.
                voice_settings:
                  type: object
                  description: ElevenLabs only. Passed through (stability, similarity_boost, style, etc.).
      responses:
        '200':
          description: Audio bytes in the requested format. Billing rides X-Kyma-* response headers. Append ?save_to_blob=1 to instead receive a JSON body with a hosted url (used by the Kyma canvas).
          headers:
            X-Kyma-Model:
              schema:
                type: string
              description: The Kyma model SKU that served the request.
            X-Kyma-Chars-Billed:
              schema:
                type: integer
              description: Characters billed for this request.
            X-Kyma-Cost-USD:
              schema:
                type: number
              description: Final cost charged for this request.
            X-Kyma-Balance-USD:
              schema:
                type: number
              description: Remaining account balance after this charge.
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
            audio/wav:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://kymaapi.com/v1
      description: Production
  /audio/music:
    post:
      operationId: createMusic
      summary: Generate music (sync)
      description: Generate a music track from a text description (ElevenLabs prompt) or lyrics (MiniMax lyrics, with optional [verse]/[chorus] tags; pass [Instrumental] for vocal-less tracks). Synchronous - returns audio bytes. Billed per track.
      tags:
      - Audio
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  type: string
                  description: 'Music model SKU (ElevenLabs or MiniMax). Non-music models return 400 not_a_music_model. This lane is paused: every model is switched off, so a request returns 404 model_not_found.'
                prompt:
                  type: string
                  description: Text description of the music. Required for ElevenLabs models. A per-model character cap applies.
                lyrics:
                  type: string
                  description: Lyrics for MiniMax models, with optional [verse]/[chorus] tags. Pass [Instrumental] for vocal-less tracks. Falls back to prompt when omitted.
                music_length_ms:
                  type: integer
                  default: 30000
                  description: 'Requested track length in milliseconds. Alias: duration_ms. Model-dependent caps apply.'
                response_format:
                  type: string
                  description: Output audio format (provider-dependent; e.g. mp3, wav, flac).
      responses:
        '200':
          description: Audio bytes. Billing rides X-Kyma-* response headers. Append ?save_to_blob=1 for a JSON body with a hosted url.
          headers:
            X-Kyma-Model:
              schema:
                type: string
              description: Model SKU that served the request.
            X-Kyma-Cost-USD:
              schema:
                type: number
              description: Final cost charged for this request.
            X-Kyma-Balance-USD:
              schema:
                type: number
              description: Remaining account balance after this charge.
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://kymaapi.com/v1
      description: Production
  /audio/sfx:
    post:
      operationId: createSoundEffect
      summary: Generate sound effect (sync)
      description: Generate a short sound effect from a text prompt (ElevenLabs). Synchronous - returns audio bytes. Billed per generation.
      tags:
      - Audio
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - prompt
              properties:
                model:
                  type: string
                  description: 'SFX model SKU. Non-SFX models return 400 not_an_sfx_model. This lane is paused: every model is switched off, so a request returns 404 model_not_found.'
                prompt:
                  type: string
                  description: 'Description of the sound effect. Alias: text.'
                duration_seconds:
                  type: number
                  description: Optional target length in seconds. Omit to let the model choose.
                response_format:
                  type: string
                  default: mp3_44100_128
                  description: Output audio format (ElevenLabs naming, e.g. mp3_44100_128).
                prompt_influence:
                  type: number
                  description: How strictly the output follows the prompt (0-1).
      responses:
        '200':
          description: Audio bytes. Billing rides X-Kyma-* response headers. Append ?save_to_blob=1 for a JSON body with a hosted url.
          headers:
            X-Kyma-Model:
              schema:
                type: string
              description: Model SKU that served the request.
            X-Kyma-Cost-USD:
              schema:
                type: number
              description: Final cost charged for this request.
            X-Kyma-Balance-USD:
              schema:
                type: number
              description: Remaining account balance after this charge.
          content:
            audio/mpeg:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://kymaapi.com/v1
      description: Production
components:
  schemas:
    PaymentRequired:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
              enum:
              - billing_error
              description: Always `billing_error`, on every surface.
            code:
              type: string
              enum:
              - model_requires_paid
              - insufficient_credits
              description: The rule that refused.
            param:
              type: string
              nullable: true
            retryable:
              type: boolean
            request_id:
              type: string
            doc_url:
              type: string
        type:
          type: string
          enum:
          - error
          description: Anthropic-compat envelope marker. Only on /v1/messages.
        topup:
          type: string
          description: Machine top-up endpoint. An agent with a wallet and no human can pay here; it is a hint in the body, never a payment challenge.
          example: https://api.kymaapi.com/v1/topup
        need_usd:
          type: number
          description: Worst-case cost of this request, USD. `insufficient_credits` only.
        have_usd:
          type: number
          description: Spendable credit at the moment of the refusal, USD. `insufficient_credits` only.
        balance:
          type: number
          description: Mirror of `details.balance`.
        required:
          type: number
          description: 'Mirror of `details.required`. Zero on `model_requires_paid`: no top-up amount makes a premium model callable on signup credit.'
        topup_url:
          type: string
          description: Billing page for a human. Mirror of `details.topup_url`.
          example: https://kymaapi.com/billing
        details:
          type: object
          properties:
            balance:
              type: number
            required:
              type: number
            topup_url:
              type: string
            hint:
              type: string
            endpoint_id:
              type: string
              description: The model the caller asked for.
          description: The nested envelope the media, audio and Anthropic-compat surfaces emit. Read this first; the top-level mirrors exist for older parsers. (/v1/embeddings emits the same envelope for a low balance, but it has its own check rather than this gate, so it carries neither code.)
      description: 402 — the access gate refused. `model_requires_paid` (signup credit is a free tier, not the whole catalogue) or `insufficient_credits` (the balance does not cover the request).
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: 'One sentence: what happened and what to do next.'
            type:
              type: string
              enum:
              - invalid_request_error
              - authentication_error
              - billing_error
              - permission_error
              - not_found_error
              - request_too_large
              - rate_limit_error
              - timeout_error
              - upstream_error
              - api_error
              description: The category. On /v1/messages, Anthropic's error type for the same condition.
            code:
              type: string
              enum:
              - missing_api_key
              - invalid_api_key
              - invalid_login
              - password_reset_required
              - invalid_google_token
              - permission_denied
              - voice_not_owned
              - session_required
              - csrf_failed
              - route_refused
              - content_refused
              - invalid_json
              - missing_parameter
              - invalid_parameter
              - wrong_endpoint
              - unsupported_content
              - unsupported_media_type
              - request_rejected
              - no_speech_detected
              - segments_unsupported
              - method_not_allowed
              - captcha_failed
              - invalid_signature
              - account_exists
              - request_too_large
              - request_exceeds_tier_limit
              - endpoint_not_found
              - endpoint_retired
              - model_not_found
              - model_retired
              - job_not_found
              - model_requires_paid
              - insufficient_credits
              - tier_required
              - payment_required
              - rate_limit_exceeded
              - concurrency_limit_exceeded
              - media_rate_exceeded
              - queue_full
              - too_many_sessions
              - too_many_attempts
              - signup_paused
              - upstream_rate_limited
              - provider_unavailable
              - model_unavailable
              - upstream_invalid_response
              - upstream_timeout
              - stream_interrupted
              - upload_timeout
              - media_paused
              - service_unavailable
              - internal_error
              - signup_failed
              - settle_failed
              description: 'Stable machine code: added, never renamed or removed. Each has an entry at https://docs.kymaapi.com/api-reference/errors'
            param:
              type: string
              nullable: true
              description: The request field at fault, or null.
            retryable:
              type: boolean
              description: Whether the same request can succeed if sent again (after `Retry-After`). Also sent as the `x-should-retry` header.
            request_id:
              type: string
              description: Same value as the `x-request-id` header. Quote it to support.
              example: req_7f3c2a9e0b1d4c6f8a2e5b7d9c1f3a5e
            doc_url:
              type: string
              description: This code's entry on the errors page.
              example: https://docs.kymaapi.com/api-reference/errors#insufficient_credits
          required:
          - message
          - type
          - code
      required:
      - error
      description: 'Every error body. On /v1/messages the same object sits in Anthropic''s envelope: `type: "error"` on top, an Anthropic `error.type`, and `request_id` also at the top level.'
    AudioBilling:
      type: object
      properties:
        duration_sec:
          type: number
          description: Audio duration in seconds.
        billable_seconds:
          type: integer
          description: 'Only present on /audio/transcriptions responses. Seconds charged: the duration rounded up to a whole second, with a 10-second minimum per request.'
        billable_minutes:
          type: integer
          description: Minutes charged, rounded up. On /audio/transcriptions this is `billable_seconds` in whole minutes, kept for compatibility; the charge is computed from `billable_seconds`.
        cost_usd:
          type: number
          description: Final cost charged for this request.
        balance_usd:
          type: number
          description: Remaining account balance after this charge.
        duration_source:
          type: string
          enum:
          - upstream_usage
          - file_bound
          description: 'Only present on /audio/understand responses. `upstream_usage`: billed seconds are the input the model consumed (audio and question). `file_bound`: the model reported no usage, so the file''s own length bound was billed.'
      description: Per-request billing breakdown for audio endpoints (transcription per second with a 10-second minimum; audio understanding per minute).
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: Seconds until the rate limit resets
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PaymentRequired:
      description: 'Payment required. One gate decides every refusal and `error.code` names the rule that fired: `model_requires_paid` (the account has never deposited and this model is outside the free tier, which `free_tier` on `GET /v1/models` states in advance) or `insufficient_credits` (the balance does not cover the request; `need_usd` and `have_usd` say by how much). `error.type` is `billing_error` on every surface, /v1/messages included. `topup` is the machine endpoint an agent can pay without a human; `topup_url` is the page for a human.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentRequired'
          examples:
            model_requires_paid:
              summary: Never funded, premium model — /chat/completions, /completions
              value:
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.5
                required: 0
                topup_url: https://kymaapi.com/billing
                error:
                  message: This model requires a funded balance. Signup credit covers lower-cost models. Top up at https://kymaapi.com/billing
                  type: billing_error
                  code: model_requires_paid
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#model_requires_paid
                details:
                  balance: 0.5
                  required: 0
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at https://kymaapi.com/billing to continue, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: claude-fable-5.1
            insufficient_credits:
              summary: Balance below the worst case — /chat/completions, /completions
              value:
                need_usd: 0.012562
                have_usd: 0.0004
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.0004
                required: 0.012562
                topup_url: https://kymaapi.com/billing
                error:
                  message: This request needs about $0.01 of credit; you have $0.0004. Top up at https://kymaapi.com/billing or lower max_tokens.
                  type: billing_error
                  code: insufficient_credits
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#insufficient_credits
                details:
                  balance: 0.0004
                  required: 0.012562
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at least $0.02 to run this model — a human can top up at https://kymaapi.com/billing, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: deepseek-v3
            model_requires_paid_messages:
              summary: Never funded, premium model — /messages (Anthropic-compat envelope)
              value:
                type: error
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.5
                required: 0
                topup_url: https://kymaapi.com/billing
                error:
                  message: This model requires a funded balance. Signup credit covers lower-cost models. Top up at https://kymaapi.com/billing
                  type: billing_error
                  code: model_requires_paid
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#model_requires_paid
                details:
                  balance: 0.5
                  required: 0
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at https://kymaapi.com/billing to continue, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: claude-fable-5.1
            model_requires_paid_media:
              summary: Never funded, premium SKU — media and audio surfaces (D3 envelope)
              value:
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.5
                required: 0
                topup_url: https://kymaapi.com/billing
                error:
                  message: 'gpt-image-2 is not in the free tier; add credits to use it. Free-tier media: gemini-3.5-transcribe, gpt-4o-mini-transcribe-2025-12-15, gpt-transcribe, minimax-image-01, whisper-v3-turbo.'
                  type: billing_error
                  code: model_requires_paid
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#model_requires_paid
                details:
                  balance: 0.5
                  required: 0
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at https://kymaapi.com/billing to continue, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: gpt-image-2
            insufficient_credits_media:
              summary: Balance below the job estimate — media and audio surfaces (D3 envelope)
              value:
                need_usd: 0.054
                have_usd: 0.01
                topup: https://api.kymaapi.com/v1/topup
                balance: 0.01
                required: 0.054
                topup_url: https://kymaapi.com/billing
                error:
                  message: This request needs about $0.05 of credit; you have $0.01. Top up at https://kymaapi.com/billing.
                  type: billing_error
                  code: insufficient_credits
                  param: null
                  retryable: false
                  doc_url: https://docs.kymaapi.com/api-reference/errors#insufficient_credits
                details:
                  balance: 0.01
                  required: 0.054
                  topup_url: https://kymaapi.com/billing
                  hint: Top up at least $0.06 to run this model — a human can top up at https://kymaapi.com/billing, or POST https://api.kymaapi.com/v1/topup to pay without one
                  endpoint_id: gpt-image-2
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Kyma API key (starts with ky-) or session token (starts with ks-)
x-refined-from:
- kymaapi-com-openapi.json
- kymaapi-com-v1-openapi.json