> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skills.video/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate TTS audio (synchronous)

> Synchronously synthesize speech from text using the resolved TTS model. Returns the generated audio URL and raw upstream payload. On failure, the response body exposes a machine-readable `code` from the TTS generation taxonomy, a sanitized `message`, and the legacy `error` field for backward compatibility.

Synchronous TTS generation. Errors are surfaced with a `TTS_GENERATION_*` `code`, a human readable `message`, and a legacy `error` field.


## OpenAPI

````yaml /openapi.json post /ai/tts/generate
openapi: 3.1.0
info:
  title: skills.video OpenAPI
  version: 1.0.0
  description: OpenAPI schema for skills.video API endpoints.
servers:
  - url: https://open.skills.video/api/v1
security: []
paths:
  /ai/tts/generate:
    post:
      summary: Generate TTS audio (synchronous)
      description: >-
        Synchronously synthesize speech from text using the resolved TTS model.
        Returns the generated audio URL and raw upstream payload. On failure,
        the response body exposes a machine-readable `code` from the TTS
        generation taxonomy, a sanitized `message`, and the legacy `error` field
        for backward compatibility.
      requestBody:
        required: true
        content:
          application/json:
            example:
              provider: minimax-tts
              model: speech-02-hd
              input:
                text: Hello world, this is a sample TTS generation.
                voice: default
                language: en
            schema:
              $ref: '#/components/schemas/TtsGenerateRequest'
      responses:
        '200':
          description: TTS generation succeeded.
          content:
            application/json:
              example:
                success: true
                data:
                  provider: minimax-tts
                  model: speech-02-hd
                  modelId: minimax-tts/speech-02-hd
                  endpoint: minimax/tts-v2
                  audio_url: https://cdn.example.com/tts/audio_abc123.mp3
                  audio:
                    url: https://cdn.example.com/tts/audio_abc123.mp3
                    content_type: audio/mpeg
                    duration: 3.2
                  output:
                    audio_url: https://cdn.example.com/tts/audio_abc123.mp3
                  logs: null
                  metrics: null
              schema:
                $ref: '#/components/schemas/TtsGenerateResponse'
        '400':
          description: TTS request was rejected as invalid.
          content:
            application/json:
              example:
                error: TTS_GENERATION_INVALID_INPUT
                code: TTS_GENERATION_INVALID_INPUT
                message: Invalid input
              schema:
                $ref: '#/components/schemas/TtsGenerationErrorResponse'
        '404':
          description: TTS model was not found or is not supported.
          content:
            application/json:
              example:
                error: TTS_GENERATION_UNSUPPORTED_MODEL
                code: TTS_GENERATION_UNSUPPORTED_MODEL
                message: TTS model not found
              schema:
                $ref: '#/components/schemas/TtsGenerationErrorResponse'
        '422':
          description: Upstream moderation rejected the request content.
          content:
            application/json:
              example:
                error: TTS_GENERATION_CONTENT_REJECTED
                code: TTS_GENERATION_CONTENT_REJECTED
                message: Request content was rejected by the moderation policy.
              schema:
                $ref: '#/components/schemas/TtsGenerationErrorResponse'
        '429':
          description: TTS generation rate limit exceeded upstream.
          content:
            application/json:
              example:
                error: TTS_GENERATION_RATE_LIMITED
                code: TTS_GENERATION_RATE_LIMITED
                message: Rate limit exceeded. Please retry later.
              schema:
                $ref: '#/components/schemas/TtsGenerationErrorResponse'
        '500':
          description: TTS generation failed before provider execution completed.
          content:
            application/json:
              example:
                error: TTS_GENERATION_FAILED
                code: TTS_GENERATION_FAILED
                message: Generation failed.
              schema:
                $ref: '#/components/schemas/TtsGenerationErrorResponse'
        '502':
          description: TTS generation failed upstream.
          content:
            application/json:
              example:
                error: TTS_GENERATION_FAILED
                code: TTS_GENERATION_FAILED
                message: Generation failed.
              schema:
                $ref: '#/components/schemas/TtsGenerationErrorResponse'
        '503':
          description: Upstream TTS provider is unavailable.
          content:
            application/json:
              example:
                error: TTS_GENERATION_PROVIDER_UNAVAILABLE
                code: TTS_GENERATION_PROVIDER_UNAVAILABLE
                message: Upstream generation provider is temporarily unavailable.
              schema:
                $ref: '#/components/schemas/TtsGenerationErrorResponse'
        '504':
          description: TTS generation exceeded the upstream timeout.
          content:
            application/json:
              example:
                error: TTS_GENERATION_TIMEOUT
                code: TTS_GENERATION_TIMEOUT
                message: Generation timed out.
              schema:
                $ref: '#/components/schemas/TtsGenerationErrorResponse'
      servers:
        - url: https://open.skills.video/api
          description: >-
            CMS host. The TTS sync endpoint lives under `/api`, not under
            `/api/v1`.
components:
  schemas:
    TtsGenerateRequest:
      type: object
      properties:
        modelId:
          description: >-
            Canonical TTS model id. Takes precedence over
            provider/model/endpoint when set.
          type: string
          minLength: 1
        provider:
          description: TTS provider key.
          type: string
          minLength: 1
        model:
          description: TTS model key (scoped to provider).
          type: string
          minLength: 1
        endpoint:
          description: >-
            Explicit upstream endpoint identifier. Optional when `modelId` or
            `provider`+`model` resolve to a known TTS spec.
          type: string
          minLength: 1
        input:
          description: >-
            Model-specific TTS input payload (text, voice, language, etc.). The
            accepted keys depend on the resolved TTS spec; see the corresponding
            model documentation.
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
    TtsGenerateResponse:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          properties:
            provider:
              anyOf:
                - type: string
                - type: 'null'
            model:
              anyOf:
                - type: string
                - type: 'null'
            modelId:
              anyOf:
                - type: string
                - type: 'null'
            endpoint:
              anyOf:
                - type: string
                - type: 'null'
            audio_url:
              anyOf:
                - type: string
                - type: 'null'
            audio:
              anyOf:
                - $ref: '#/components/schemas/TtsAudioAsset'
                - type: 'null'
            output:
              anyOf:
                - type: object
                  propertyNames:
                    type: string
                  additionalProperties: {}
                - type: 'null'
            logs:
              anyOf:
                - {}
                - type: 'null'
            metrics:
              anyOf:
                - {}
                - type: 'null'
          required:
            - provider
            - model
            - audio_url
            - audio
            - output
            - logs
            - metrics
          additionalProperties: false
      required:
        - success
        - data
      additionalProperties: false
    TtsGenerationErrorResponse:
      type: object
      properties:
        error:
          description: >-
            Legacy machine-readable error field. Prefer `code` for new
            integrations.
          type: string
        code:
          description: >-
            TTS generation error code. `*_FAILED` is the generic fallback; more
            specific codes (`*_TIMEOUT`, `*_RATE_LIMITED`,
            `*_PROVIDER_UNAVAILABLE`, `*_UNSUPPORTED_MODEL`, `*_INVALID_INPUT`,
            `*_INSUFFICIENT_CREDITS`, `*_CONTENT_REJECTED`) are surfaced when
            applicable.
          type: string
          enum:
            - TTS_GENERATION_FAILED
            - TTS_GENERATION_TIMEOUT
            - TTS_GENERATION_RATE_LIMITED
            - TTS_GENERATION_PROVIDER_UNAVAILABLE
            - TTS_GENERATION_UNSUPPORTED_MODEL
            - TTS_GENERATION_INVALID_INPUT
            - TTS_GENERATION_INSUFFICIENT_CREDITS
            - TTS_GENERATION_CONTENT_REJECTED
        message:
          description: Human readable error message. Upstream vendor names are redacted.
          type: string
        errors:
          description: Field-level validation errors when available.
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
              code:
                type: string
            required:
              - path
              - message
              - code
            additionalProperties: false
        details:
          description: Additional structured error details when available.
        requested:
          description: Requested credits when the error is insufficient credits.
          type: number
        available:
          description: Available credits when the error is insufficient credits.
          type: number
      required:
        - code
        - message
      additionalProperties: false
    TtsAudioAsset:
      type: object
      properties:
        url:
          anyOf:
            - type: string
            - type: 'null'
        content_type:
          anyOf:
            - type: string
            - type: 'null'
        file_name:
          anyOf:
            - type: string
            - type: 'null'
        file_size:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        duration:
          anyOf:
            - type: number
            - type: 'null'
      additionalProperties: {}

````