Fish Audio

https://docs.fish.audio
Admin
Fish Audio is an AI platform for text-to-speech, voice cloning, and audio storytelling that...
Tokens:797,928
Snippets:4,948
Trust Score:9.2
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install dependencies for Python example

Source: https://docs.fish.audio/api-reference/endpoint/openapi-v1/text-to-speech-live-with-timestamps

Install the required Python packages for the WebSocket client example.

```bash
pip install ormsgpack websockets
```

--------------------------------

### Install dependencies for the voice agent quickstart

Source: https://docs.fish.audio/agents/quickstart

Initializes a Node.js project and installs the required dependencies: Express for the backend, @fishaudio/agent-client for the browser SDK, and Vite as a dev dependency to serve the frontend and proxy API requests.

```bash
npm init -y
npm install express @fishaudio/agent-client
npm install --save-dev vite

```

--------------------------------

### Go example to list knowledge sources

Source: https://docs.fish.audio/api-reference/endpoint/agent/list-knowledge-sources

Uses the net/http package to create a GET request with the Authorization header and prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fish.audio/v1/agent/knowledge-sources?page_size=30"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Go GET test batch

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-test-batch

Go example using net/http to GET a test batch. Replace the placeholders with your agent ID, batch ID, and token.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fish.audio/v1/agent/agents/{agent_id}/test-batches/{batch_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Install Fish Audio SDK (Python and JavaScript)

Source: https://docs.fish.audio/developer-guide/sdk-guide/quickstart

Install the official Fish Audio SDK. The Python SDK is the recommended starting point; the JavaScript SDK is in early release. The optional Python extra enables local audio playback and requires ffmpeg.

```bash
pip install fish-audio-sdk

# optional: local audio playback (needs ffmpeg)
pip install "fish-audio-sdk[utils]"

```

```bash
npm install fish-audio

```

--------------------------------

### Ruby example to list knowledge sources

Source: https://docs.fish.audio/api-reference/endpoint/agent/list-knowledge-sources

Uses Net::HTTP to perform a GET request with SSL enabled and the Authorization header, printing the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.fish.audio/v1/agent/knowledge-sources?page_size=30")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Get Test Run with Go net/http

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-test-run

Go example using the standard net/http package to perform a GET request to the Fish Audio API endpoint. Requires a valid Bearer token and run_id.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fish.audio/v1/agent/test-runs/{run_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

--------------------------------

### Go example to list agents

Source: https://docs.fish.audio/api-reference/endpoint/agent/list-agents

Uses the net/http package to send a GET request to the agents endpoint with a Bearer token and prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fish.audio/v1/agent/agents?publication_state=all&page_size=30"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Put it together: backend, Vite proxy, and frontend

Source: https://docs.fish.audio/llms-full.txt

Complete local setup: a backend route that creates the session with your API key, and a page that starts the call. The frontend is served by Vite, which proxies `/api` to the backend so the browser never sees your key.

```bash
npm init -y
npm install express @fishaudio/agent-client
npm install --save-dev vite
```

```javascript
import express from "express";

const app = express();

app.post("/api/voice-session", async (req, res) => {
  const upstream = await fetch("https://api.fish.audio/v1/agent/sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FISH_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: process.env.AGENT_ID,
      timezone: "Asia/Tokyo", // your user's IANA timezone
    }),
  });
  if (!upstream.ok) {
    console.error("session creation failed:", upstream.status);
    return res.status(502).json({ error: "session_unavailable" });
  }
  res.json(await upstream.json());
});

app.listen(3001, () => console.log("backend on http://localhost:3001"));
```

```javascript
export default {
  server: {
    proxy: { "/api": "http://localhost:3001" },
  },
};
```

```html
<!doctype html>
<button id="start">Start call</button>
<button id="end" disabled>Hang up</button>
<pre id="log"></pre>
<script type="module" src="/main.js"></script>
```

```javascript
import { AgentSession } from "@fishaudio/agent-client";

const startButton = document.getElementById("start");
const endButton = document.getElementById("end");
const log = (line) => (document.getElementById("log").textContent += line + "\n");

let session;

// Start from a click: browsers only grant the microphone and
// audio playback inside a user gesture.
startButton.onclick = async () => {
  const sessionToken = await fetch("/api/voice-session", { method: "POST" })
    .then((r) => r.json());
```

--------------------------------

### 200 Response Example

Source: https://docs.fish.audio/api-reference/endpoint/wallet/get-user-package

Example of a successful 200 response from the Get User Package endpoint. Contains user ID, package type, total and balance amounts, subscription details, and trial usage flag.

```json
{
  "user_id": "<string>",
  "type": "<string>",
  "total": 123,
  "balance": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "stripe_subscription_id": "<string>",
  "stripe_price_id": "<string>",
  "billing_period": "<string>",
  "current_period_end": "2023-11-07T05:31:56Z",
  "cancel_at_period_end": true,
  "cancel_at": "2023-11-07T05:31:56Z",
  "scheduled_change": {},
  "last_synced_at": "2023-11-07T05:31:56Z",
  "subscription_currency": "<string>",
  "subscription_status": "<string>",
  "extra_balance": 0,
  "has_used_trial": false
}

```

--------------------------------

### Install fish-audio-sdk

Source: https://docs.fish.audio/api-reference/sdk/python/overview

Install the Fish Audio Python SDK. The second command installs the package with audio playback utilities.

```bash
pip install fish-audio-sdk

# With audio playback utilities
pip install fish-audio-sdk[utils]
```

--------------------------------

### Java Unirest example to list knowledge sources

Source: https://docs.fish.audio/api-reference/endpoint/agent/list-knowledge-sources

Uses the Unirest library to send a GET request with the Authorization header and returns the response as a string.

```java
HttpResponse<String> response = Unirest.get("https://api.fish.audio/v1/agent/knowledge-sources?page_size=30")
  .header("Authorization", "Bearer <token>")
  .asString();
```

--------------------------------

### Install @fishaudio/agent-client with npm, pnpm, or yarn

Source: https://docs.fish.audio/agents/deploy/web-sdk

Install the @fishaudio/agent-client package using npm, pnpm, or yarn. These are alternative package manager commands for the same installation.

```bash
npm install @fishaudio/agent-client

```

```bash
pnpm add @fishaudio/agent-client

```

```bash
yarn add @fishaudio/agent-client

```

--------------------------------

### Install only the fish-audio-sdk skill

Source: https://docs.fish.audio/developer-guide/resources/coding-agents

Installs only the fish-audio-sdk skill.

```bash
npx skills add https://docs.fish.audio --skill fish-audio-sdk

```

--------------------------------

### JavaScript fetch example to list knowledge sources

Source: https://docs.fish.audio/api-reference/endpoint/agent/list-knowledge-sources

Uses the fetch API to make a GET request, parsing the JSON response and logging it to the console.

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.fish.audio/v1/agent/knowledge-sources?page_size=30', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Start a public agent session with AgentSession.start

Source: https://docs.fish.audio/llms-full.txt

Start a public agent session from the browser. The JavaScript SDK creates the session directly with the Fish Audio API and connects the audio. The curl example shows the equivalent API call; it requires the Origin header to match an allowed origin, otherwise the request is rejected with 403.

```javascript
import { AgentSession } from "@fishaudio/agent-client";

const session = await AgentSession.start({
  agentId: "YOUR_AGENT_ID",
});

session.on("agentResponse", ({ text }) => console.log("Agent:", text));
```

```bash
# No Authorization header. The Origin header is checked instead.
# Browsers send Origin automatically; curl must set it explicitly.
curl --request POST https://api.fish.audio/v1/agent/sessions \
  --header "Content-Type: application/json" \
  --header "Origin: https://app.example.com" \
  --data '{ "agent_id": "YOUR_AGENT_ID" }'
```

--------------------------------

### Get API Credit Success Response

Source: https://docs.fish.audio/api-reference/endpoint/wallet/get-api-credit

Example success response (HTTP 200) from the Get API Credit endpoint.

```json
{
  "_id": "<string>",
  "user_id": "<string>",
  "credit": "<string>",
  "cumulative_top_up": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "has_phone_sha256": true,
  "has_free_credit": true
}
```

--------------------------------

### Get Agent Test - HTTP Request Examples

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-test

Send a GET request to the Fish Audio API endpoint to retrieve a test by its ID. Each example uses the same URL and Authorization header, with language-specific HTTP client libraries. Replace the placeholder token and test ID before running.

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.fish.audio/v1/agent/tests/{test_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fish.audio/v1/agent/tests/{test_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fish.audio/v1/agent/tests/{test_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://api.fish.audio/v1/agent/tests/{test_id}")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.fish.audio/v1/agent/tests/{test_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### AgentSession.start

Source: https://docs.fish.audio/llms-full.txt

Documentation for the AgentSession.start method, including all options and an example.

```APIDOC
## AgentSession.start

### Description
Starts a new agent session with the given options. This is the primary entry point for creating a session with the Fish Audio agent.

### Method
start

### Parameters
#### Options
- **agentId** (string) - Required (exactly one of agentId or sessionToken) - A public agent id.
- **sessionToken** (SessionToken) - Required (exactly one of agentId or sessionToken) - The JSON your backend received from `POST /v1/agent/sessions`.
- **serverUrl** (string) - Optional - API base used in `agentId` mode. Default `https://api.fish.audio`.
- **clientTools** (Record<string, ClientToolHandler>) - Optional - Handlers for client tools declared on the agent.
- **clientToolTimeoutMs** (number) - Optional - Per-handler timeout for client tools, in milliseconds. Default `15000`.
- **overrides** (SessionOverrides) - Optional - Per-session config overrides (`agentId` mode only; with `sessionToken`, your backend sends them when creating the session). Keyless sessions accept only `voice_id` and `language`; the prompt-shaping fields are rejected with `400`.
- **dynamicVariables** (Record<string, string | number | boolean>) - Optional - Values for `{{placeholders}}` in the agent config (`agentId` mode only).
- **language** (SessionLanguage) - Optional - Shorthand for `overrides.language` (`agentId` mode only). Omit it to use the agent's configured speaking language; any other value is rejected with `422`.
- **toolEvents** (boolean) - Optional - Whether tool lifecycle events reach this client (default `true`; `agentId` mode only, with `sessionToken` your backend sets `tool_events`).
- **timezone** (string) - Optional - IANA timezone for the agent's sense of local time. When omitted, the SDK still sends the browser timezone as a lower-priority hint (`client_timezone`).
- **worldContext** (boolean) - Optional - Whether the agent knows the current date and time (default `true`; `agentId` mode only, with `sessionToken` your backend sets `world_context`).
- **endUserId** (string) - Optional - Your identifier for the end user, stored on the session and echoed in webhooks (`agentId` mode only; with `sessionToken` your backend sets `end_user_id`).
- **metadata** (object) - Optional - Your own key-values, stored on the session record and returned verbatim (`agentId` mode only; with `sessionToken` your backend sets `metadata`).
- **microphone** (boolean) - Optional - Capture the microphone on start (default `true`). `false` joins muted with no permission prompt; the first `setMicMuted(false)` captures it.
- **audio** ({ inputDeviceId?, outputDeviceId? }) - Optional - Pick specific microphone and output devices. `start()` rejects with `device_change_failed` if the output device cannot be selected.
- **wakeLock** (boolean) - Optional - Hold a screen wake lock while the session is live (default `true`). A denied or unsupported wake lock is silent.
- **callbacks** (Partial<AgentSessionCallbacks>) - Optional - Shorthand for `.on()`: each `onXxx` key subscribes the `xxx` event. From 0.2.1, a key that is not a known event name throws a `TypeError`.

### Request Example
```javascript
const session = await AgentSession.start({
  sessionToken,
  callbacks: {
    onUserTranscript: ({ text, final }) => renderUserBubble(text, final),
    onAgentResponseDelta: ({ text }) => renderAgentBubble(text),
    onModeChange: mode => setOrbState(mode),
    onDisconnect: ({ reason }) => showCallEnded(reason),
    onError: error => console.error(error.code),
  },
});
```

### Response
Returns a Promise that resolves to an `AgentSession` instance.

### Errors
- `400` - Rejected if `overrides` contains prompt-shaping fields in keyless sessions.
- `422` - Rejected if `language` is not one of the 52 supported languages.
- `device_change_failed` - Rejected if the output device cannot be selected.
```

--------------------------------

### Python: Install SDK, generate speech, run script, and play audio

Source: https://docs.fish.audio/llms-full.txt

Python SDK workflow: install fish-audio-sdk, create a script that initializes FishAudio (reads FISH_API_KEY), converts text to speech, saves the audio as welcome.mp3, then run and play the file.

```bash
pip install fish-audio-sdk
```

```python
from fishaudio import FishAudio
from fishaudio.utils import save

# Initialize with your API key
client = FishAudio()  # reads FISH_API_KEY

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

print("✓ Audio saved to welcome.mp3")
```

```bash
python generate_speech.py
```

```bash
# On macOS
afplay welcome.mp3

# On Linux
mpg123 welcome.mp3

# On Windows
start welcome.mp3
```

--------------------------------

### Java Unirest GET test batch

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-test-batch

Java example using Unirest to GET a test batch. Replace the placeholders with your agent ID, batch ID, and token.

```java
HttpResponse<String> response = Unirest.get("https://api.fish.audio/v1/agent/agents/{agent_id}/test-batches/{batch_id}")
  .header("Authorization", "Bearer <token>")
  .asString();
```

--------------------------------

### PHP cURL GET test batch

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-test-batch

PHP example using cURL to GET a test batch. Replace the placeholders with your agent ID, batch ID, and token.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fish.audio/v1/agent/agents/{agent_id}/test-batches/{batch_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### JavaScript fetch GET test batch

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-test-batch

JavaScript example using fetch to GET a test batch. Replace the placeholders with your agent ID, batch ID, and token.

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.fish.audio/v1/agent/agents/{agent_id}/test-batches/{batch_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Python GET test batch

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-test-batch

Python example using the requests library to GET a test batch. Replace the placeholders with your agent ID, batch ID, and token.

```python
import requests

url = "https://api.fish.audio/v1/agent/agents/{agent_id}/test-batches/{batch_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### List available skills before installing

Source: https://docs.fish.audio/developer-guide/resources/coding-agents

Lists the available skills before installing them.

```bash
npx skills add https://docs.fish.audio --list

```

--------------------------------

### Ruby Net::HTTP GET test batch

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-test-batch

Ruby example using Net::HTTP to GET a test batch. Replace the placeholders with your agent ID, batch ID, and token.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.fish.audio/v1/agent/agents/{agent_id}/test-batches/{batch_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Get Test Run with Java Unirest

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-test-run

Java example using Unirest to send a GET request to the Fish Audio API endpoint. Requires a valid Bearer token and run_id.

```java
HttpResponse<String> response = Unirest.get("https://api.fish.audio/v1/agent/test-runs/{run_id}")
  .header("Authorization", "Bearer <token>")
  .asString();

```

--------------------------------

### JavaScript: Install SDK, generate speech, run script, and play audio

Source: https://docs.fish.audio/llms-full.txt

JavaScript SDK workflow: install fish-audio, create a script that uses FishAudioClient with the FISH_API_KEY environment variable, converts text to speech, writes the audio buffer to welcome.mp3, then run and play the file.

```bash
npm install fish-audio
```

```javascript
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");
```

```bash
node generate_speech.mjs
```

```bash
# On macOS
afplay welcome.mp3

# On Linux
mpg123 welcome.mp3

# On Windows
start welcome.mp3
```

--------------------------------

### 200 Response Example

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-phone-number

Example of a successful 200 response body for the Get Phone Number endpoint. It includes fields such as phone_number_id, workspace_id, phone_number, provider, agent_id, status, and various configuration options.

```json
{
  "phone_number_id": "<string>",
  "workspace_id": "<string>",
  "phone_number": "<string>",
  "provider": "livekit",
  "agent_id": "<string>",
  "status": "provisioning",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "label": "",
  "cold_transfer_use_original_caller": true,
  "cold_transfer_use_original_caller_effective": true,
  "caller_id_sync_status": "carrier_managed",
  "caller_id_sync_error": "",
  "status_detail": "",
  "supports_outbound": false,
  "termination_uri": "<string>",
  "inbound_auth_username": "<string>",
  "inbound_allowed_addresses": [
    "<string>"
  ],
  "termination_transport": "<string>",
  "termination_auth_username": "<string>",
  "termination_headers": {}
}
```

--------------------------------

### Get Test Run with Ruby Net::HTTP

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-test-run

Ruby example using Net::HTTP to send a GET request to the Fish Audio API endpoint. Requires a valid Bearer token and run_id.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.fish.audio/v1/agent/test-runs/{run_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

```

--------------------------------

### AgentSession.start()

Source: https://docs.fish.audio/llms-full.txt

Starts an agent session with the given configuration, including client tools and audio settings. Throws FishAgentError if the session cannot be created.

```APIDOC
## [SDK] AgentSession.start()

### Description
Starts an agent session with the given configuration, including client tools and audio settings. Throws `FishAgentError` if the session cannot be created.

### Method
SDK method call

### Endpoint
`AgentSession.start(config)`

### Parameters
#### Configuration Object
- **agentId** (string) - Required - The ID of the agent to start a session with.
- **clientTools** (object) - Optional - A map of tool names to handler functions. Each handler receives a `params` object and returns a value (or a Promise) that is sent back to the agent.
- **clientToolTimeoutMs** (number) - Optional - Timeout in milliseconds for client tool handlers. Default is 15000.
- **audio.outputDeviceId** (string) - Optional - The ID of the audio output device to use. If set and the device cannot be activated, a `device_change_failed` error is thrown.

### Request Example
```javascript
const session = await AgentSession.start({
  agentId: "YOUR_AGENT_ID",
  clientTools: {
    open_page: async params => {
      showPanel(String(params.page));
      return { opened: true };
    },
  },
});
```

### Response
#### Success Response
Returns an `AgentSession` instance that emits events and provides methods for interaction.

#### Error Response
Throws `FishAgentError` with a `code` property. Possible codes include `session_request_failed`, `agent_not_public`, `origin_forbidden`, `unsupported_transport`, `mic_permission_denied`, `device_change_failed`, `connection_failed`, `session_expired`, `tool_failed`, `tool_timeout`, `provider_error`, and `internal_error`.
```

--------------------------------

### List Agents Using Tool with Go net/http

Source: https://docs.fish.audio/api-reference/endpoint/agent/list-agents-using-tool

Go example using the net/http package to list agents using a tool. Replace {tool_id} and <token> with your values.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fish.audio/v1/agent/tools/{tool_id}/agents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Get Test Run with PHP cURL

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-test-run

PHP example using cURL to send a GET request to the Fish Audio API endpoint for retrieving a test run. Requires a valid Bearer token and run_id.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fish.audio/v1/agent/test-runs/{run_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

```

--------------------------------

### Install @fishaudio/agent-client

Source: https://docs.fish.audio/agents/quickstart

Installs the Fish Audio agent client SDK for browser-based connections.

```bash
npm install @fishaudio/agent-client
```

--------------------------------

### AgentSession.start()

Source: https://docs.fish.audio/agents/deploy/web-sdk

Creates the session, connects, and opens the microphone in one call. Authenticate one of two ways: `agentId` for public agents or `sessionToken` for private agents.

```APIDOC
## AgentSession.start()

### Description
Creates the session, connects, and opens the microphone in one call. Authenticate one of two ways: `agentId` for public agents or `sessionToken` for private agents.

### Method
start

### Endpoint
AgentSession.start()

### Parameters
#### Options
- **agentId** (string) - Optional - Public agent ID. Exactly one of `agentId` or `sessionToken` is required.
- **sessionToken** (SessionToken) - Optional - JSON received from `POST /v1/agent/sessions`. Exactly one of `agentId` or `sessionToken` is required.
- **serverUrl** (string) - Optional - API base used in `agentId` mode. Default `https://api.fish.audio`.
- **clientTools** (Record<string, ClientToolHandler>) - Optional - Handlers for client tools declared on the agent.
- **clientToolTimeoutMs** (number) - Optional - Per-handler timeout for client tools, in milliseconds. Default `15000`.
- **overrides** (SessionOverrides) - Optional - Per-session config overrides (`agentId` mode only). Keyless sessions accept only `voice_id` and `language`; prompt-shaping fields rejected with `400`.
- **dynamicVariables** (Record<string, string | number | boolean>) - Optional - Values for `{{placeholders}}` in the agent config (`agentId` mode only).
- **language** (SessionLanguage) - Optional - Shorthand for `overrides.language` (`agentId` mode only). Omit to use agent's configured language; any other value rejected with `422`.
- **toolEvents** (boolean) - Optional - Whether tool lifecycle events reach this client (default `true`; `agentId` mode only).
- **timezone** (string) - Optional - IANA timezone for the agent's sense of local time.
- **worldContext** (boolean) - Optional - Whether the agent knows the current date and time (default `true`; `agentId` mode only).
- **endUserId** (string) - Optional - Your identifier for the end user (`agentId` mode only).
- **metadata** (object) - Optional - Your own key-values stored on the session (`agentId` mode only).
- **microphone** (boolean) - Optional - Capture the microphone on start (default `true`).
- **audio** (object) - Optional - Pick specific microphone and output devices. `start()` rejects with `device_change_failed` if output device cannot be selected.
- **wakeLock** (boolean) - Optional - Hold a screen wake lock while session is live (default `true`).
- **callbacks** (Partial<AgentSessionCallbacks>) - Optional - Shorthand for `.on()`: each `onXxx` key subscribes the `xxx` event.

### Request Example
```js
const session = await AgentSession.start({
  agentId: "YOUR_AGENT_ID",
});
```

### Response
#### Success Response
- **session** (AgentSession) - The created session object.

#### Error Handling
- Rejects with `FishAgentError` if session creation, microphone permission, or connection fails.
```

--------------------------------

### Alignment Shape JSON Example

Source: https://docs.fish.audio/api-reference/endpoint/openapi-v1/text-to-speech-stream-with-timestamps

Shows the structure of a non-null alignment object in the stream. `start` and `end` are seconds from the chunk's audio start; add `chunk_audio_offset_sec` for the full timeline. `alignment` can be null before the first snapshot.

```json
{
  "audio_base64": "SUQzBAAAAAAA...",
  "content": "Hello world",
  "chunk_seq": 0,
  "chunk_audio_offset_sec": 0.0,
  "alignment": {
    "audio_duration": 0.86,
    "segments": [
      {
        "text": "Hello",
        "start": 0,
        "end": 0.42
      },
      {
        "text": "world",
        "start": 0.42,
        "end": 0.86
      }
    ]
  }
}
```

--------------------------------

### Connect and wire up all channels

Source: https://docs.fish.audio/agents/deploy/protocol

Complete wiring example for connecting to a LiveKit session and handling all data channels.

```APIDOC
## [WebSocket] LiveKit Session Channels

### Description
Connect to a LiveKit session and wire up all data channels for agent communication.

### Method
WebSocket (LiveKit protocol)

### Endpoint
`livekit_url` and `token` from session-creation response

### Parameters
#### Query Parameters
- **livekit_url** (string) - Required - The LiveKit server URL from the session-creation response.
- **token** (string) - Required - The access token from the session-creation response.

### Request Example
```javascript
import { Room, RoomEvent } from 'livekit-client';

const room = new Room();

// Register all handlers BEFORE connecting: the agent may already be
// speaking when you join, and `lk.agent.state` is delivered on join.

// Agent events: reliable data packets on the `agent-event` topic
room.on(RoomEvent.DataReceived, (payload, participant, kind, topic) => {
  if (topic !== 'agent-event') return;
  const event = JSON.parse(new TextDecoder().decode(payload));
  // event.type: 'client_tool.call' | 'tool.started' | 'tool.completed' | ...
});

// Transcription: text streams on the `lk.transcription` topic
room.registerTextStreamHandler('lk.transcription', async (reader, participant) => {
  const segmentId = reader.info.attributes?.['lk.segment_id'];
  const isFinal = reader.info.attributes?.['lk.transcription_final'] === 'true';
  const text = await reader.readAll();
  // participant.identity tells you whether this is the user's or the agent's segment
});

// Agent state: sticky `lk.agent.state` participant attribute
room.on(RoomEvent.ParticipantAttributesChanged, (changed, participant) => {
  if ('lk.agent.state' in changed) {
    console.log(participant.attributes['lk.agent.state']);
  }
});

// Agent speech: attach the agent's audio track when it arrives
room.on(RoomEvent.TrackSubscribed, (track) => {
  document.body.appendChild(track.attach());
});

// Now connect, using `livekit_url` and `token` from the
// session-creation response above, and publish your microphone
await room.connect(livekitUrl, token);
await room.localParticipant.setMicrophoneEnabled(true);

// Client events: publish JSON on the `client-event` topic
function send(event: object) {
  return room.localParticipant.publishData(
    new TextEncoder().encode(JSON.stringify(event)),
    { reliable: true, topic: 'client-event' },
  );
}

await send({ type: 'user.message', text: "What's my balance?" });
```

### Response
#### Success Response (200)
- **Audio tracks** - The agent's speech is received as an audio track.
- **agent-event** - Control events: client tool calls, tool lifecycle, errors, session end.
- **lk.transcription** - Streaming transcripts for both sides.
- **lk.agent.state** - Agent pipeline state (sticky).

#### Response Example
```json
{
  "event": {
    "type": "client_tool.call"
  }
}
```
```

--------------------------------

### Install from npm with registerWidget()

Source: https://docs.fish.audio/agents/deploy/widget

For bundlers, install @fishaudio/agent-widget and call registerWidget() once. Importing the package has no side effects; the call defines the <fish-agent> element.

```javascript
import { registerWidget } from "@fishaudio/agent-widget";
registerWidget(); // defines <fish-agent>
```

--------------------------------

### Dynamic Voice Switching with stream_websocket and streamSpeech

Source: https://docs.fish.audio/developer-guide/best-practices/real-time-streaming

Shows how to switch voices mid-stream by starting a new stream with a different reference_id. The Python example uses stream_websocket with a generator, while the JavaScript example uses streamSpeech with a request object.

```python
# Start with one voice

def text1():
    yield "Hello from voice one."

audio1 = client.tts.stream_websocket(text1(), reference_id="voice1")
for chunk in audio1:
    play_audio(chunk)

# Switch to another
def text2():
    yield "And now voice two!"

audio2 = client.tts.stream_websocket(text2(), reference_id="voice2")
for chunk in audio2:
    play_audio(chunk)
```

```javascript
// Start with one voice
const request1 = { reference_id: "voice1" };
streamSpeech("Hello from voice one.", request1);

// Switch to another
const request2 = { reference_id: "voice2" };
streamSpeech("And now voice two!", request2);
```

--------------------------------

### Get, update, and delete a voice with Python and curl

Source: https://docs.fish.audio/llms-full.txt

Shows how to inspect a single model by ID, update its metadata (only passed fields change), and delete it. The curl examples use the model endpoint with GET, PATCH, and DELETE methods.

```python
# Inspect one model
voice = client.voices.get("YOUR_VOICE_ID")
print(voice.title, voice.state)

# Update metadata (only the fields you pass change)
client.voices.update(
    "YOUR_VOICE_ID",
    title="Updated title",
    visibility="unlist",
)

# Delete
client.voices.delete("YOUR_VOICE_ID")
```

```bash
# Inspect one model
curl https://api.fish.audio/model/YOUR_VOICE_ID \
  --header "Authorization: Bearer $FISH_API_KEY"

# Update metadata
curl --request PATCH https://api.fish.audio/model/YOUR_VOICE_ID \
  --header "Authorization: Bearer $FISH_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "title": "Updated title", "visibility": "unlist" }'

# Delete
curl --request DELETE https://api.fish.audio/model/YOUR_VOICE_ID \
  --header "Authorization: Bearer $FISH_API_KEY"
```

--------------------------------

### AgentSession.start

Source: https://docs.fish.audio/agents/deploy/web-sdk

Initializes a new agent session with optional client tools.

```APIDOC
## AgentSession.start(options)

### Description
Starts a new agent session. You can provide an `agentId` and an optional `clientTools` object to define handlers for tools the agent can invoke.

### Parameters
- **options** (object) - Required
  - **agentId** (string) - Required: The ID of the agent to connect to.
  - **clientTools** (object) - Optional: A map of tool names to async handler functions.

### Example
```javascript
const session = await AgentSession.start({
  agentId: "YOUR_AGENT_ID",
  clientTools: {
    open_page: async params => {
      showPanel(String(params.page));
      return { opened: true };
    },
  },
});
```
```

--------------------------------

### Get Agent Version - Success Response

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-agent-version

Example response body for a successful Get Agent Version request. Contains the agent version number, configuration hash, publication timestamp, full agent configuration, and version title/description.

```json
{
  "version_number": 123,
  "config_hash": "<string>",
  "published_at": "2023-11-07T05:31:56Z",
  "config": {
    "agent_id": "<string>",
    "config_hash": "<string>",
    "prompt": {
      "system_prompt": "",
      "first_message_mode": "prompt",
      "first_message": "Hi! Thanks for calling — how can I help you today?",
      "first_message_prompt": "Greet the caller and ask what you can help with."
    },
    "voice": {
      "voice_id": "b347db033a6549378b48d00acb0d06cd",
      "speaking_language": "en",
      "expressive": false,
      "speed": 1
    },
    "asr": {
      "model": "deepgram:nova-3",
      "multilingual": false,
      "strict_language": false,
      "keyterms": [
        "<string>"
      ]
    },
    "conversation": {
      "max_duration_seconds": 1800,
      "response_wait_ms": 550,
      "eagerness": "balanced",
      "response_max_wait_ms": 123,
      "interruptible": true,
      "interruption_sensitivity": "balanced",
      "interruption_ignore_phrases": [],
      "speculative_response": true,
      "reengage_enabled": false,
      "hangup_after_seconds": 60,
      "hangup_farewell_enabled": false,
      "record_audio": true,
      "timezone": "",
      "transfer_destinations": [],
      "outbound": {
        "amd_enabled": true,
        "voicemail": {
          "action": "hangup",
          "message": ""
        }
      }
    },
    "tools": {
      "enabled": true,
      "tool_ids": [
        "<string>"
      ],
      "system_tools": {
        "hang_up_call": false
      }
    },
    "webhooks": {
      "conversation_init": {
        "url": "<string>",
        "has_secret": false,
        "timeout_seconds": 5
      },
      "post_call": [
        {
          "url": "<string>",
          "has_secret": false
        }
      ]
    },
    "knowledge_base": {
      "enabled": false,
      "knowledge_source_ids": [
        "<string>"
      ]
    },
    "analysis": {
      "summary": {
        "enabled": true,
      "prompt": "<string>",
        "language": "en"
      },
      "data_fields": [
        {
          "name": "<string>",
          "type": "text",
          "description": "",
          "enum_options": [
            "<string>"
          ]
        }
      ],
      "criteria": [
        {
          "name": "<string>",
          "description": ""
        }
      ]
    },
    "guardrails": {
      "focus": false,
      "manipulation": false
    },
    "llm": {
      "model": "google/gemini-3.6-flash",
      "custom": {
        "base_url": "<string>",
        "model": "<string>",
        "api_key": null
      }
    },
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "version_title": "<string>",
  "version_description": "<string>"
}
```

--------------------------------

### Install Fish Audio skills

Source: https://docs.fish.audio/developer-guide/resources/coding-agents

Installs both Fish Audio skills into your agent. Run `npx skills update` later to refresh them.

```bash
npx skills add https://docs.fish.audio

```

--------------------------------

### Create and start a browser agent session

Source: https://docs.fish.audio/llms-full.txt

Backend creates a session with a POST to /v1/agent/sessions using your API key, then the frontend starts an AgentSession with the returned token. The API key never ships to the browser.

```bash
curl --request POST https://api.fish.audio/v1/agent/sessions \
  --header "Authorization: Bearer $FISH_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "agent_id": "YOUR_AGENT_ID" }'
# → 201 session token. Return it to your frontend as-is
```

```javascript
import { AgentSession } from "@fishaudio/agent-client";

// sessionToken = the create-session response, passed through unchanged
const session = await AgentSession.start({ sessionToken });
```

--------------------------------

### Get Agent - 200 Response

Source: https://docs.fish.audio/api-reference/endpoint/agent/get-agent

Example 200 response body for the Get Agent endpoint. Shows the agent object with fields like agent_id, workspace_id, name, status, publication_state, timestamps, description, public_enabled, allowed_origins, and overrides_allowed.

```json
{
  "agent_id": "<string>",
  "workspace_id": "<string>",
  "name": "<string>",
  "status": "active",
  "publication_state": "live",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "description": "",
  "public_enabled": false,
  "allowed_origins": [
    "<string>"
  ],
  "overrides_allowed": [
    "first_message"
  ]
}
```

--------------------------------

### Converting text to speech and saving audio

Source: https://docs.fish.audio/llms-full.txt

Example usage of the convert method to get complete audio, then play or save it.

```python
from fishaudio import AsyncFishAudio
from fishaudio.utils import play, save

client = AsyncFishAudio(api_key="...")

# Get complete audio
audio = await client.tts.convert(text="Hello world")

# Play it
play(audio)

# Or save it
save(audio, "output.mp3")
```

--------------------------------

### Play audio examples

Source: https://docs.fish.audio/llms-full.txt

Example usage of the play function. It shows direct playback, Jupyter notebook playback, and forcing the sounddevice fallback. Requires a FishAudio client with an API key.

```python
from fishaudio import FishAudio, play

client = FishAudio(api_key="...")
audio = client.tts.convert(text="Hello world")

# Play directly
play(audio)

# In Jupyter notebook
play(audio, notebook=True)

# Force sounddevice fallback
play(audio, use_ffmpeg=False)
```
Tokens:
Raw