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

# Quick Start

> Generate your first AI voice with Fish Audio in under 5 minutes

export const AudioTranscript = ({voices, page}) => {
  const resolvedVoices = voices?.length ? voices : (() => {
    if (!page) return [];
    const baseUrl = 'https://pub-b995142090474379a930b856ab79b4d4.r2.dev/audio';
    const pageVoices = [{
      id: '8ef4a238714b45718ce04243307c57a7',
      name: 'E-girl'
    }, {
      id: '802e3bc2b27e49c2995d23ef70e6ac89',
      name: 'Energetic Male'
    }, {
      id: '933563129e564b19a115bedd57b7406a',
      name: 'Sarah'
    }, {
      id: 'bf322df2096a46f18c579d0baa36f41d',
      name: 'Adrian'
    }, {
      id: 'b347db033a6549378b48d00acb0d06cd',
      name: 'Selene'
    }, {
      id: '536d3a5e000945adb7038665781a4aca',
      name: 'Ethan'
    }];
    return pageVoices.map(voice => ({
      ...voice,
      url: `${baseUrl}/${page}/${voice.id}.mp3`
    }));
  })();
  const [selectedVoice, setSelectedVoice] = useState(0);
  const [isPlaying, setIsPlaying] = useState(false);
  const [currentTime, setCurrentTime] = useState(0);
  const [duration, setDuration] = useState(0);
  const [isDropdownOpen, setIsDropdownOpen] = useState(false);
  const audioRef = useRef(null);
  const dropdownRef = useRef(null);
  useEffect(() => {
    const audio = audioRef.current;
    if (!audio) return;
    const updateTime = () => setCurrentTime(audio.currentTime);
    const updateDuration = () => setDuration(audio.duration);
    const handleEnded = () => setIsPlaying(false);
    audio.addEventListener('timeupdate', updateTime);
    audio.addEventListener('loadedmetadata', updateDuration);
    audio.addEventListener('ended', handleEnded);
    return () => {
      audio.removeEventListener('timeupdate', updateTime);
      audio.removeEventListener('loadedmetadata', updateDuration);
      audio.removeEventListener('ended', handleEnded);
    };
  }, []);
  useEffect(() => {
    const handleClickOutside = event => {
      if (dropdownRef.current && !dropdownRef.current.contains(event.target)) {
        setIsDropdownOpen(false);
      }
    };
    if (isDropdownOpen) {
      document.addEventListener('mousedown', handleClickOutside);
    }
    return () => {
      document.removeEventListener('mousedown', handleClickOutside);
    };
  }, [isDropdownOpen]);
  useEffect(() => {
    if (audioRef.current) {
      audioRef.current.pause();
      audioRef.current.load();
      setIsPlaying(false);
      setCurrentTime(0);
    }
  }, [selectedVoice]);
  const togglePlay = () => {
    if (isPlaying) {
      audioRef.current.pause();
    } else {
      audioRef.current.play();
    }
    setIsPlaying(!isPlaying);
  };
  const handleProgressChange = e => {
    const newTime = parseFloat(e.target.value);
    audioRef.current.currentTime = newTime;
    setCurrentTime(newTime);
  };
  const formatTime = time => {
    if (isNaN(time)) return '0:00';
    const minutes = Math.floor(time / 60);
    const seconds = Math.floor(time % 60);
    return `${minutes}:${seconds.toString().padStart(2, '0')}`;
  };
  const currentVoice = resolvedVoices[selectedVoice];
  return <div className="border rounded-lg bg-card border-gray-200 dark:border-gray-800">
      {}
      <div className="grid grid-cols-3 items-center px-3 py-1.5 bg-muted border-b border-gray-200 dark:border-gray-800">
        <span className="text-xs font-medium">Listen to Page</span>

        <span className="text-xs font-semibold text-muted-foreground text-center">Powered by Fish Audio S2 Pro</span>

        {resolvedVoices.length > 1 ? <div className="relative justify-self-end" ref={dropdownRef}>
            <button onClick={() => setIsDropdownOpen(!isDropdownOpen)} className="flex items-center gap-1.5 px-3 py-1 rounded-full bg-muted hover:bg-gray-200 dark:hover:bg-gray-700 transition-all duration-200 cursor-pointer text-xs">
              <span className="text-muted-foreground">Voice:</span>
              <span className="font-medium">{resolvedVoices[selectedVoice]?.name}</span>
              <svg className={`w-3 h-3 transition-transform duration-200 ${isDropdownOpen ? 'rotate-180' : ''}`} fill="none" stroke="currentColor" viewBox="0 0 24 24">
                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
              </svg>
            </button>

            {isDropdownOpen && <div className="absolute right-0 mt-1 w-auto bg-white dark:bg-black border border-gray-200 dark:border-gray-700 rounded-lg overflow-hidden z-50">
                {resolvedVoices.map((voice, index) => <button key={index} onClick={() => {
    setSelectedVoice(index);
    setIsDropdownOpen(false);
  }} className={`w-full px-3 py-1.5 text-left text-xs hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors flex items-center gap-2 ${index === selectedVoice ? 'bg-gray-100 dark:bg-gray-800 font-medium' : ''}`}>
                    {voice.id && <img src={`https://public-platform.r2.fish.audio/coverimage/${voice.id}`} alt={voice.name} className="w-5 h-5 rounded-full m-0 flex-shrink-0 object-cover" />}
                    <span className="flex-1 whitespace-nowrap">{voice.name}</span>
                  </button>)}
              </div>}
          </div> : <div className="justify-self-end" />}
      </div>

      {}
      <div className="px-3 py-1.5 bg-card">
        <audio ref={audioRef} src={currentVoice?.url} preload="metadata" />

        <div className="flex items-center gap-2">
          {}
          <button onClick={togglePlay} className="flex-shrink-0 w-6 h-6 flex items-center justify-center bg-gray-300 dark:bg-gray-600 text-gray-800 dark:text-gray-200 rounded-full hover:opacity-80 transition-opacity relative overflow-hidden" aria-label={isPlaying ? 'Pause' : 'Play'}>
            <div className="transition-transform duration-300 ease-in-out" style={{
    transform: isPlaying ? 'rotate(180deg)' : 'rotate(0deg)'
  }}>
              {isPlaying ? <svg className="w-3 h-3" fill="currentColor" viewBox="0 0 24 24">
                  <path d="M6 4h4v16H6V4zm8 0h4v16h-4V4z" />
                </svg> : <svg className="w-3 h-3 ml-0.5" fill="currentColor" viewBox="0 0 24 24">
                  <path d="M8 5v14l11-7z" />
                </svg>}
            </div>
          </button>

          {}
          <div className="flex-1 flex items-center gap-2">
            <span className="text-xs font-mono text-gray-500 dark:text-gray-400 min-w-[35px]">
              {formatTime(currentTime)}
            </span>

            <div className="flex-1 relative h-1 bg-gray-200 dark:bg-gray-700 rounded-full overflow-hidden">
              <div className="absolute top-0 left-0 h-full bg-gray-400 dark:bg-gray-500 transition-all duration-100" style={{
    width: `${duration ? currentTime / duration * 100 : 0}%`
  }} />
              <input type="range" min="0" max={duration || 0} value={currentTime} onChange={handleProgressChange} className="absolute top-0 left-0 w-full h-full opacity-0 cursor-pointer" />
            </div>
            <span className="text-xs font-mono text-gray-500 dark:text-gray-400 min-w-[35px]">
              {formatTime(duration)}
            </span>
          </div>
        </div>
      </div>
    </div>;
};

## Overview

This guide will walk you through generating your first text-to-speech audio with Fish Audio. By the end, you'll have converted text into natural-sounding speech using our API.

## Prerequisites

<AccordionGroup>
  <Accordion icon="user-plus" title="Create a Fish Audio account">
    Sign up for a free Fish Audio account to get started with our API.

    1. Go to [fish.audio/auth/signup](https://fish.audio/auth/signup)
    2. Fill in your details to create an account, complete steps to verify your account.
    3. Log in to your account and navigate to the [API section](https://fish.audio/app/api-keys)
  </Accordion>

  <Accordion icon="key" title="Get your API key">
    Once you have an account, you'll need an API key to authenticate your requests.

    1. Log in to your [Fish Audio Dashboard](https://fish.audio/app/api-keys/)
    2. Navigate to the API Keys section
    3. Click "Create New Key" and give it a descriptive name, set a expiration if desired
    4. Copy your key and store it securely

    <Warning>Keep your API key secret! Never commit it to version control or share it publicly.</Warning>
  </Accordion>
</AccordionGroup>

## Your First TTS Request

Choose your preferred method to generate speech:

<Tabs>
  <Tab title="cURL">
    <Steps>
      <Step title="Set your API key">
        Store your API key as an environment variable (recommended approach):

        ```bash theme={null}
        export FISH_API_KEY="replace_me"
        ```
      </Step>

      <Step title="Make the TTS request">
        Run this [cURL](https://curl.se/) command to generate your first speech:

        ```bash theme={null}
        curl -X POST https://api.fish.audio/v1/tts \
          -H "Authorization: Bearer $FISH_API_KEY" \
          -H "Content-Type: application/json" \
          -H "model: s2-pro" \
          -d '{
            "text": "Hello! Welcome to Fish Audio. This is my first AI-generated voice.",
            "format": "mp3"
          }' \
          --output welcome.mp3
        ```
      </Step>

      <Step title="Play your audio">
        The audio has been saved as `welcome.mp3`. You can play it by:

        * Double-clicking the file or opening it in any media player
        * Or using the command line:

        ```bash theme={null}
        # On macOS
        afplay welcome.mp3

        # On Linux
        mpg123 welcome.mp3

        # On Windows
        start welcome.mp3
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python">
    <Steps>
      <Step title="Install the SDK">
        ```bash theme={null}
        pip install fish-audio-sdk
        ```
      </Step>

      <Step title="Generate speech">
        Create a Python script:

        ```python theme={null}
        from fishaudio import FishAudio
        from fishaudio.utils import save

        # Initialize with your API key
        client = FishAudio(api_key="your_api_key_here")

        # Generate speech
        audio = client.tts.convert(text="Hello! Welcome to Fish Audio.")
        save(audio, "welcome.mp3")

        print("✓ Audio saved to welcome.mp3")
        ```
      </Step>

      <Step title="Run the script">
        ```bash theme={null}
        python generate_speech.py
        ```
      </Step>

      <Step title="Play your audio">
        The audio has been saved as `welcome.mp3`. You can play it by:

        * Double-clicking the file or opening it in any media player
        * Or using the command line:

        ```bash theme={null}
        # On macOS
        afplay welcome.mp3

        # On Linux
        mpg123 welcome.mp3

        # On Windows
        start welcome.mp3
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="JavaScript">
    <Steps>
      <Step title="Install the SDK">
        ```bash theme={null}
        npm install fish-audio
        ```
      </Step>

      <Step title="Generate speech">
        Create a JavaScript script:

        ```javascript theme={null}
        import { FishAudioClient } from "fish-audio";
        import { writeFile } from "fs/promises";

        const fishAudio = new FishAudioClient({ apiKey: process.env.FISH_API_KEY });

        const audio = await fishAudio.textToSpeech.convert({
          text: "Hello, world!",
        });

        const buffer = Buffer.from(await new Response(audio).arrayBuffer());
        await writeFile("welcome.mp3", buffer);

        console.log("✓ Audio saved to welcome.mp3");
        ```
      </Step>

      <Step title="Run the script">
        ```bash theme={null}
        node generate_speech.mjs
        ```
      </Step>

      <Step title="Play your audio">
        The audio has been saved as `welcome.mp3`. You can play it by:

        * Double-clicking the file or opening it in any media player
        * Or using the command line:

        ```bash theme={null}
        # On macOS
        afplay welcome.mp3

        # On Linux
        mpg123 welcome.mp3

        # On Windows
        start welcome.mp3
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Customizing Your Voice

The examples above use the default voice. To use a different voice, add the `reference_id` parameter with a model ID from [fish.audio](https://fish.audio). You can find the model ID in the URL or use the copy button when viewing any voice.

Choose a voice to try:

<Tabs>
  <Tab title="E-Girl Voice">
    From: [https://fish.audio/m/8ef4a238714b45718ce04243307c57a7](https://fish.audio/m/8ef4a238714b45718ce04243307c57a7)

    ```bash theme={null}
    export REFERENCE_ID="8ef4a238714b45718ce04243307c57a7"
    ```
  </Tab>

  <Tab title="Energetic Male">
    From: [https://fish.audio/m/802e3bc2b27e49c2995d23ef70e6ac89](https://fish.audio/m/802e3bc2b27e49c2995d23ef70e6ac89)

    ```bash theme={null}
    export REFERENCE_ID="802e3bc2b27e49c2995d23ef70e6ac89"
    ```
  </Tab>
</Tabs>

Then generate speech with your chosen voice:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.fish.audio/v1/tts \
      -H "Authorization: Bearer $FISH_API_KEY" \
      -H "Content-Type: application/json" \
      -H "model: s2" \
      -d '{
        "text": "This is a custom voice from Fish Audio! You can explore hundreds of different voices on the platform, or even create your own.",
        "reference_id": "'"$REFERENCE_ID"'",
        "format": "mp3"
      }' \
      --output custom_voice.mp3
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from fishaudio import FishAudio
    from fishaudio.utils import save

    client = FishAudio(api_key="your_api_key_here")

    # Generate speech with custom voice
    audio = client.tts.convert(
        text="This is a custom voice from Fish Audio! You can explore hundreds of different voices on the platform, or even create your own.",
        reference_id=os.environ.get("REFERENCE_ID")
    )
    save(audio, "custom_voice.mp3")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { FishAudioClient } from "fish-audio";
    import { writeFile } from "fs/promises";

    const fishAudio = new FishAudioClient({ apiKey: process.env.FISH_API_KEY });

    const audio = await fishAudio.textToSpeech.convert({
      text: "This is a custom voice from Fish Audio! You can explore hundreds of different voices on the platform, or even create your own.",
      reference_id: process.env.REFERENCE_ID,
    });

    const buffer = Buffer.from(await new Response(audio).arrayBuffer());
    await writeFile("custom_voice.mp3", buffer);

    console.log("✓ Audio saved to custom_voice.mp3");
    ```
  </Tab>
</Tabs>

## Support

Need help? Check out these resources:

* [API Reference](/api-reference/introduction) - Complete API documentation
* [Create a Voice Clone](/api-reference/endpoint/model/create-model) - Create a voice clone model
* [Generate Speech](/api-reference/endpoint/openapi-v1/text-to-speech) - Generate realistic speech
* [Real-time Streaming](/developer-guide/sdk-guide/python/websocket) - WebSocket for real-time streaming
* [Discord Community](https://discord.com/invite/dF9Db2Tt3Y) - Get help from the community
* [Support Email](mailto:support@fish.audio) - Contact our support team