openapi: 3.0.3 info: title: FishAudio Personal Voice Synthesis for Coze version: 1.0.1 description: >- Import this file into a private Coze cloud plugin. It creates a persistent personal private voice from a directly downloadable authorized audio URL, then synthesizes the requested text asynchronously. Every user supplies their own Fish Audio API key through the Authorization tool parameter. servers: - url: https://fishaudio.org paths: /api/open/v1/speech/voice-clone-tts/jobs: post: operationId: create_personal_voice summary: Create a personal voice and synthesize text description: >- Creates one persistent private voice, then starts one TTS job. Save data.id and reuse the same Idempotency-Key only when retrying this exact request. A new generation must use a new key. parameters: - name: Authorization in: header required: true description: Customer Fish Audio API key in the format Bearer YOUR_API_KEY. example: Bearer YOUR_FISH_AUDIO_API_KEY schema: type: string - name: Idempotency-Key in: header required: true description: >- A unique client-generated value. Reuse it only to retry the same request; use a new value for every new generation. example: coze-personal-voice-20260820-001 schema: type: string maxLength: 200 requestBody: required: true content: application/json: schema: type: object required: - source_audio_url - text properties: source_audio_url: type: string format: uri description: >- Customer-owned or authorized reference audio URL directly downloadable by Fish Audio. Maximum download size is 10 MB. text: type: string minLength: 1 maxLength: 5000 description: Text to synthesize with the newly created private voice. voice_name: type: string minLength: 1 maxLength: 100 description: Optional name for the persistent private voice. file_name: type: string minLength: 1 maxLength: 255 description: Optional source filename including an audio extension. model_id: type: string default: fishaudio-s21pro-flash description: Fish Audio speech synthesis model. Use the default for the first test. enum: - fishaudio-s21pro - fishaudio-s21pro-flash - fishaudio-s2pro - fishaudio-s1 format: type: string default: mp3 description: Output audio format. enum: - mp3 - wav speed: type: number minimum: 0.5 maximum: 2 default: 1 description: Speech speed multiplier from 0.5 to 2. volume: type: number minimum: -20 maximum: 20 default: 0 description: Output volume adjustment from -20 to 20. stability: type: number minimum: 0.5 maximum: 1.5 description: Optional voice stability control from 0.5 to 1.5. similarity: type: number minimum: 0.5 maximum: 1.5 description: Optional voice similarity control from 0.5 to 1.5. language: type: string maxLength: 32 description: Optional language hint supported by the selected model. instruction: type: string maxLength: 1600 description: Optional style, role, dialect, pacing, or emotion instruction. text_normalization: type: boolean default: true description: Normalize text before synthesis. Keep true unless special formatting is required. responses: '200': description: Coze-compatible success response schema; the live API accepts the job with HTTP 202. content: application/json: schema: type: object properties: success: type: boolean description: Whether the API request was accepted successfully. message: type: string description: Human-readable API response message. requestId: type: string description: Request identifier for troubleshooting. data: type: object description: Created voice and asynchronous synthesis job details. properties: id: type: string description: Save this value as jobId for subsequent queries. status: type: string description: Current job status. enum: - pending - processing - completed - failed stage: type: string description: Current processing stage. progress: type: number description: Processing progress from 0 to 100. voice_id: type: string description: Persistent private voice ID created from the authorized audio. voice_name: type: string description: Name assigned to the persistent private voice. audio_url: type: string format: uri description: Temporary playback URL when synthesis is completed. download_url: type: string format: uri description: Temporary download URL when synthesis is completed. expires_at: type: string description: Expiration time of the temporary audio URLs. error_code: type: string description: Error code when the job fails. error_message: type: string description: Error details when the job fails. quota_remaining: type: number description: Remaining Fish Audio account quota after the request. created_at: type: string description: Job creation time. updated_at: type: string description: Most recent job update time. completed_at: type: string description: Job completion time when available. '202': description: Voice created and TTS job accepted by the live API. content: application/json: schema: type: object properties: success: type: boolean description: Whether the API request was accepted successfully. requestId: type: string description: Request identifier for troubleshooting. data: type: object description: Accepted asynchronous synthesis job details. properties: id: type: string description: Save this value as jobId for subsequent queries. status: type: string description: Current job status. voice_id: type: string description: Persistent private voice ID created from the authorized audio. /api/open/v1/speech/voice-clone-tts/jobs/{jobId}: get: operationId: get_personal_voice_job summary: Query a personal voice synthesis job description: >- Query the original job ID. Polling does not create another voice or charge again. parameters: - name: Authorization in: header required: true description: Customer Fish Audio API key in the format Bearer YOUR_API_KEY. example: Bearer YOUR_FISH_AUDIO_API_KEY schema: type: string - name: jobId in: path required: true description: The data.id returned by create_personal_voice. schema: type: string responses: '200': description: Job status returned successfully. content: application/json: schema: type: object properties: success: type: boolean description: Whether the query completed successfully. message: type: string description: Human-readable API response message. requestId: type: string description: Request identifier for troubleshooting. data: type: object description: Current private voice synthesis job details. properties: id: type: string description: Original job ID. status: type: string description: Current job status. enum: - pending - processing - completed - failed stage: type: string description: Current processing stage. progress: type: number description: Processing progress from 0 to 100. voice_id: type: string description: Persistent private voice ID created from the authorized audio. voice_name: type: string description: Name assigned to the persistent private voice. audio_url: type: string format: uri description: Temporary playback URL when synthesis is completed. download_url: type: string format: uri description: Temporary download URL when synthesis is completed. expires_at: type: string description: Expiration time of the temporary audio URLs. error_code: type: string description: Error code when the job fails. error_message: type: string description: Error details when the job fails. quota_remaining: type: number description: Remaining Fish Audio account quota after the request. created_at: type: string description: Job creation time. updated_at: type: string description: Most recent job update time. completed_at: type: string description: Job completion time when available.