openapi: 3.0.3
info:
  title: FishAudio TTS 文字转语音
  version: 1.0.0
  description: >-
    Import this file into a private Coze cloud plugin. Every user supplies their
    own Fish Audio API key through the Authorization tool parameter.
servers:
  - url: https://fishaudio.org
paths:
  /api/open/v1/speech/tts:
    post:
      operationId: generate_tts
      summary: Generate speech and return temporary audio URLs
      description: >-
        Converts text to speech. Keep cache set to true so the response is JSON
        that Coze can parse instead of raw audio bytes.
      parameters:
        - $ref: '#/components/parameters/Authorization'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TtsRequest'
      responses:
        '200':
          description: Speech generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TtsResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '402':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '408':
          $ref: '#/components/responses/ErrorResponse'
        '409':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'
components:
  parameters:
    Authorization:
      name: Authorization
      in: header
      required: true
      description: Customer Fish Audio API key in the format Bearer YOUR_API_KEY.
      schema:
        type: string
      example: Bearer YOUR_FISH_AUDIO_API_KEY
  schemas:
    TtsRequest:
      type: object
      required:
        - text
        - voiceId
        - cache
      properties:
        text:
          type: string
          minLength: 1
          description: Text to synthesize. Use short text for the first test.
          example: Hello from Fish Audio.
        voiceId:
          type: string
          description: A system or custom Fish Audio voice ID available to the customer account.
          example: 00a1b221-6137-4b73-ad62-b0cbce134167
        modelId:
          type: string
          description: Optional TTS engine model ID.
          example: fishaudio-s21pro-flash
        format:
          type: string
          enum:
            - mp3
            - wav
          default: mp3
        cache:
          type: boolean
          enum:
            - true
          default: true
          description: Must remain true so Coze receives JSON with audio_url.
        speed:
          type: number
          minimum: 0.5
          maximum: 2
          default: 1
        volume:
          type: number
          minimum: -20
          maximum: 20
          default: 0
        stability:
          type: number
          minimum: 0.5
          maximum: 1.5
          default: 1
        similarity:
          type: number
          minimum: 0.5
          maximum: 1.5
          default: 1
        pitch:
          type: number
          minimum: -12
          maximum: 12
          default: 0
        language:
          type: string
          description: Optional language hint supported by the selected model.
        emotion:
          type: string
          description: Optional emotion supported by the selected model.
        instruction:
          type: string
          maxLength: 1600
          description: Optional style, role, dialect, pacing, or emotion instruction.
        textNormalization:
          type: boolean
          default: true
    TtsResponse:
      type: object
      required:
        - success
        - audio_url
        - format
        - characters_used
        - credits_used
        - quota_remaining
        - expires_at
      properties:
        success:
          type: boolean
        audio_url:
          type: string
          format: uri
          description: Temporary URL for playback. The asset currently expires after three days.
        playback_url:
          type: string
          format: uri
        download_url:
          type: string
          format: uri
        asset_id:
          type: string
        format:
          type: string
        characters_used:
          type: integer
        credits_used:
          type: integer
        quota_remaining:
          type: integer
        expires_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        requestId:
          type: string
      additionalProperties: true
  responses:
    ErrorResponse:
      description: Fish Audio API error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'