SpeechifyAI API documentation - TTS + Voice Agent API

https://speechify.ai
Admin
Speechify API documentation — integrate text-to-speech and real-time agents into your apps. Simba...
Tokens:757,658
Snippets:5,086
Trust Score:7.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Get File Request Examples

Source: https://docs.speechify.ai/agents/api-reference/v1/files/-fileId-/get?explorer=true

Examples for retrieving file details using different programming languages.

```python
import requests

# Get File (GET /v1/files/:file_id)
response = requests.get(
  "https://api.speechify.ai/v1/files/file_01jqr8x9zg5k2m3n4p5q6r7s8t",
  headers={
    "Authorization": "Bearer "
  },
)

print(response.json())
```

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

### Get Store Response Example

Source: https://docs.speechify.ai/agents/api-reference/v1/stores/-storeId-/get

Example JSON response returned when successfully retrieving a store.

```json
{
  "id": "store_01jqr8x9zg5k2m3n4p5q6r7s8t",
  "name": "news",
  "description": "string",
  "project_id": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "used_bytes": 1,
  "updated_at": "2024-01-15T09:30:00Z"
}
```

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

### List Test Folders Python Example

Source: https://docs.speechify.ai/agents/api-reference/v1/agents/tests/folders/get?explorer=true

A Python example using the requests library to perform a GET request to the test folders endpoint.

```python
import requests

# List Test Folders (GET /v1/agents/tests/folders)
response = requests.get(
  "https://api.speechify.ai/v1/agents/tests/folders",
  headers={
    "Authorization": "Bearer "
  },
)

print(response.json())
```

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

### Get Skill Response Example

Source: https://docs.speechify.ai/agents/api-reference/v1/skills/-skillId-/get

A successful 200 OK response containing the skill's metadata, configuration, and version information.

```json
{
  "id": "skill_01jqr8x9zg5k2m3n4p5q6r7s8t",
  "name": "Book an appointment",
  "description": "string",
  "project_id": "string",
  "version": 1,
  "latest_version": 1,
  "instructions": "string",
  "tool_ids": [
    "string"
  ],
  "knowledge_base_ids": [
    "string"
  ],
  "variables": {},
  "attached_agent_count": 1,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}
```

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

### Get Project Request

Source: https://docs.speechify.ai/agents/api-reference/v1/projects/-id-/get?explorer=true

Example request to retrieve project details using the Python requests library.

```python
import requests  
  
# Get Project (GET /v1/projects/:project_id)  
response = requests.get(  
  "https://api.speechify.ai/v1/projects/proj_01jqr8x9zg5k2m3n4p5q6r7s8t",  
  headers={  
    "Authorization": "Bearer "  
  },  
)  
  
print(response.json())
```

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

### startAgent(options)

Source: https://docs.speechify.ai/agents/guides/deploy/embed

Initializes and starts a new agent session, returning an AgentHandle for further interaction.

```APIDOC
## startAgent(options)

### Description
Starts the agent session. Returns a promise that resolves to an `AgentHandle` object.

### Parameters
- **agentId** (string) - Required - The unique identifier for the agent.
- **onStatus** (function) - Optional - Callback triggered when the agent status changes.
- **onMessage** (function) - Optional - Callback triggered when a message is received.
- **onError** (function) - Optional - Callback triggered for failures occurring after the call is established.

### Returns
- **AgentHandle** (object) - An object providing methods to interact with the active agent session.
```

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

### Get Agent Run Request

Source: https://docs.speechify.ai/agents/api-reference/v1/agents/-id-/runs/-runId-/get?explorer=true

Example request to retrieve an agent run using the GET method.

```python
import requests  
  
# Get Agent Run (GET /v1/agents/:agent_id/runs/:run_id)  
response = requests.get(  
  "https://api.speechify.ai/v1/agents/agent_01jqr8x9zg5k2m3n4p5q6r7s8t/runs/arun_01kr410dd3yrst4chn5kn0t78f",  
  headers={  
    "Authorization": "Bearer "  
  },  
)  
  
print(response.json())
```

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

### Initialize Speechify SDK in Python

Source: https://docs.speechify.ai/agents/api-reference/get-started/authentication

Initialize the client by reading the SPEECHIFY_API_KEY from the environment or by passing the token explicitly.

```python
from speechify import Speechify

# Reads SPEECHIFY_API_KEY from the environment
client = Speechify()

# ...or pass it explicitly
client = Speechify(token="your-api-key")
```

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

### Run the shim

Source: https://docs.speechify.ai/build/guides/integrations/deepgram

Set the required environment variables and execute the shim binary.

```bash
export SPEECHIFY_API_KEY=sk_your_key_here
export SHIM_ADDR=:8771

./bin/openai
```

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

### Get Team Request

Source: https://docs.speechify.ai/agents/api-reference/v1/agents/teams/-teamId-/get?explorer=true

Example requests to retrieve team details using the GET /v1/agents/teams/:team_id endpoint.

```python
import requests  
  
# Get Team (GET /v1/agents/teams/:team_id)  
response = requests.get(  
  "https://api.speechify.ai/v1/agents/teams/team_01jqr8x9zg5k2m3n4p5q6r7s8t",  
  headers={  
    "Authorization": "Bearer "  
  },  
)  
  
print(response.json())
```

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

### Install dependencies

Source: https://docs.speechify.ai/build/guides/integrations/livekit

Install the required LiveKit agent packages, plugins, and environment management tools.

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install "livekit-agents[codecs]>=1.6.5" \
  "livekit-plugins-speechify>=1.6.5" \
  "livekit-plugins-deepgram>=1.6.5" \
  "livekit-plugins-openai>=1.6.5" \
  python-dotenv
```

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

### Get Caller Request

Source: https://docs.speechify.ai/agents/api-reference/v1/agents/callers/-id-/get?explorer=true

Example requests to retrieve a specific caller's details using the GET method.

```python
import requests

# Get Caller (GET /v1/agents/callers/:caller_id)
response = requests.get(
  "https://api.speechify.ai/v1/agents/callers/caller_01jqr8x9zg5k2m3n4p5q6r7s8t",
  headers={
    "Authorization": "Bearer "
  },
)

print(response.json())
```

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

### Create Project Request

Source: https://docs.speechify.ai/agents/api-reference/v1/projects/post?explorer=true

Example request to create a new project named 'Production'.

```python
import requests

# Create Project (POST /v1/projects)
response = requests.post(
  "https://api.speechify.ai/v1/projects",
  headers={
    "Authorization": "Bearer "
  },
  json={
    "name": "Production"
  },
)

print(response.json())
```

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

### List Phone Numbers Python Example

Source: https://docs.speechify.ai/agents/api-reference/v1/agents/phone-numbers/get?explorer=true

This example demonstrates how to use the requests library to perform a GET request to the phone numbers endpoint.

```python
import requests  
  
# List Phone Numbers (GET /v1/agents/phone-numbers)  
response = requests.get(  
  "https://api.speechify.ai/v1/agents/phone-numbers",  
  headers={  
    "Authorization": "Bearer "  
  },  
)  
  
print(response.json())
```

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

### Create Voice TypeScript SDK Example

Source: https://docs.speechify.ai/build/api-reference/v1/voices/post

Example of initializing the Speechify client and calling the create method using the TypeScript SDK.

```typescript
import { SpeechifyClient } from "@speechify/api";

async function main() {
    const client = new SpeechifyClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.voices.create({});
}
main();
```

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

### Get Team Request

Source: https://docs.speechify.ai/agents/api-reference/v1/agents/teams/-teamId-/get

Example cURL request to retrieve a team by its unique identifier.

```bash
curl https://api.speechify.ai/v1/agents/teams/team_01jqr8x9zg5k2m3n4p5q6r7s8t \
  -H "Authorization: Bearer <token>"
```

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

### Promote Project cURL Request

Source: https://docs.speechify.ai/agents/api-reference/v1/projects/-id-/promote

Example request to promote a project configuration using cURL.

```bash
curl -X POST https://api.speechify.ai/v1/projects/proj_01jqr8x9zg5k2m3n4p5q6r7s8t/promote \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "target_project_id": "proj_01jqr8x9zg5k2m3n4p5q6r7s8t"
}'
```

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

### Get Caller Request

Source: https://docs.speechify.ai/agents/api-reference/v1/agents/callers/-id-/get

Example cURL request to retrieve a specific caller by their ID.

```bash
curl https://api.speechify.ai/v1/agents/callers/caller_01jqr8x9zg5k2m3n4p5q6r7s8t \
  -H "Authorization: Bearer <token>"
```

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

### Get Document Request

Source: https://docs.speechify.ai/agents/api-reference/v1/stores/-storeId-/collections/-collection-/documents/-docId-/get?explorer=true

Example request to retrieve a document using the Python requests library.

```python
import requests  
  
# Get Document (GET /v1/stores/:store_id/collections/:collection/documents/:document_id)  
response = requests.get(  
  "https://api.speechify.ai/v1/stores/store_01jqr8x9zg5k2m3n4p5q6r7s8t/collections/items/documents/2026-09-02-openai-ships",  
  headers={  
    "Authorization": "Bearer "  
  },  
)  
  
print(response.json())
```

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

### Project Stats Response Example

Source: https://docs.speechify.ai/agents/api-reference/v1/projects/-id-/stats

A successful 200 OK response containing the live resource counts for a project.

```json
{
  "resource_counts": {
    "agents": 5,
    "knowledge_bases": 2,
    "tools": 3,
    "phone_numbers": 1,
    "audio_assets": 10,
    "conversations": 128,
    "callers": 45,
    "agent_tests": 8,
    "batch_calls": 2,
    "agent_test_suite_runs": 3,
    "memories": 214
  }
}
```

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

### Get Contact Response

Source: https://docs.speechify.ai/agents/api-reference/v1/contacts/-contactId-/get

Example JSON response returned when successfully fetching a contact by its ID.

```json
{
  "id": "contact_01k603xzbcwc8tr7std0hk1dbs",
  "tenant_id": "ws_01k603xzbcwc8tr7std0hk1dbs",
  "metadata": {},
  "identifiers": [
    {
      "id": "ident_01k603xzbcwc8tr7std0hk1dbs",
      "contact_id": "contact_01k603xzbcwc8tr7std0hk1dbs",
      "kind": "external_id",
      "value": "+12025550100",
      "asserted_by": "api",
      "created_at": "2024-01-15T09:30:00Z",
      "verified_at": "2024-01-15T09:30:00Z"
    }
  ],
  "agent_ids": [
    "agent_01jqr8x9zg5k2m3n4p5q6r7s8t"
  ],
  "first_seen_at": "2024-01-15T09:30:00Z",
  "last_seen_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "display_name": "string"
}
```

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

### Get Suite Run Request

Source: https://docs.speechify.ai/agents/api-reference/v1/agents/tests/suite-runs/-id-/get?explorer=true

Example cURL request to retrieve a suite run by its ID.

```bash
$| curl https://api.speechify.ai/v1/agents/tests/suite-runs/srun_01jqr8x9zg5k2m3n4p5q6r7s8t \  
---|---  
>|      -H "Authorization: Bearer <token>"
```

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

### Basic SSML Example

Source: https://docs.speechify.ai/build/guides/text-to-speech/ssml

A simple example of wrapping text in a speak tag.

```xml
<speak>Welcome to SpeechifyAI Build.</speak>
```

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

### Python SDK Get Voice

Source: https://docs.speechify.ai/build/api-reference/v1/voices/-id-/get

Example usage of the Speechify Python SDK to fetch a voice by ID.

```python
from speechify import Speechify

client = Speechify(
    token="YOUR_TOKEN_HERE",
)

client.voices.get(
    voice_id="voice_id",
)
```

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

### Create Sitemap Import Request

Source: https://docs.speechify.ai/agents/api-reference/v1/agents/knowledge-bases/-id-/documents/sitemap?explorer=true

Example cURL command to initiate a sitemap import for a specific knowledge base.

```bash
curl -X POST https://api.speechify.ai/v1/agents/knowledge-bases/kb_01jqr8x9zg5k2m3n4p5q6r7s8t/documents/sitemap \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "url": "https://example.com/webhook",
  "folder_id": "kfolder_01krdk9hzct70r12s7z5a4xtsh"
}'
```

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

### TypeScript SDK Get Voice

Source: https://docs.speechify.ai/build/api-reference/v1/voices/-id-/get

Example usage of the Speechify TypeScript SDK to fetch a voice by ID.

```typescript
import { SpeechifyClient } from "@speechify/api";

async function main() {
    const client = new SpeechifyClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.voices.get({
        voiceId: "voice_id",
    });
}
main();
```

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

### Get Store Request

Source: https://docs.speechify.ai/agents/api-reference/v1/stores/-storeId-/get?explorer=true

Example request to retrieve store details using the Python requests library.

```python
import requests

# Get Store (GET /v1/stores/:store_id)
response = requests.get(
  "https://api.speechify.ai/v1/stores/store_01jqr8x9zg5k2m3n4p5q6r7s8t",
  headers={
    "Authorization": "Bearer "
  },
)

print(response.json())
```

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

### Build the Vapi shim

Source: https://docs.speechify.ai/build/guides/integrations/vapi

Commands to clone the repository and build the Vapi shim binary using the Go toolchain.

```bash
git clone https://github.com/Speechify-AI/tts-shims
cd tts-shims
make vapi
```

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

### Get Skill Request

Source: https://docs.speechify.ai/agents/api-reference/v1/skills/-skillId-/get?explorer=true

Example request to retrieve a specific skill using the Python requests library.

```python
import requests  
  
# Get Skill (GET /v1/skills/:skill_id)  
response = requests.get(  
  "https://api.speechify.ai/v1/skills/skill_01jqr8x9zg5k2m3n4p5q6r7s8t",  
  headers={  
    "Authorization": "Bearer "  
  },  
)  
  
print(response.json())
```

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

### List Agent Run Steps Request

Source: https://docs.speechify.ai/agents/api-reference/v1/agents/-id-/runs/-runId-/steps

Example cURL command to fetch the steps for a specific agent run using an authorization token.

```bash
curl https://api.speechify.ai/v1/agents/agent_01jqr8x9zg5k2m3n4p5q6r7s8t/runs/arun_01kr410dd3yrst4chn5kn0t78f/steps \
  -H "Authorization: Bearer <token>"
```

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

### Create Folder Request

Source: https://docs.speechify.ai/agents/api-reference/v1/agents/knowledge-bases/-id-/folders/post?explorer=true

Example of how to create a folder in a knowledge base using the Python requests library.

```python
1| import requests  
---|---  
2|   
3| # Create Folder (POST /v1/agents/knowledge-bases/:kb_id/folders)  
4| response = requests.post(  
5|   "https://api.speechify.ai/v1/agents/knowledge-bases/kb_01jqr8x9zg5k2m3n4p5q6r7s8t/folders",  
6|   headers={  
7|     "Authorization": "Bearer "  
8|   },  
9|   json={  
10|     "name": "Example name",  
11|     "parent_folder_id": "kfolder_01krdk9hzct70r12s7z5a4xtsh"  
12|   },  
13| )  
14|   
15| print(response.json())
```

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

### Get Contact Request

Source: https://docs.speechify.ai/agents/api-reference/v1/contacts/-contactId-/get?explorer=true

Example request to retrieve contact details using the Python requests library.

```python
import requests  
  
# Get Contact (GET /v1/contacts/:contact_id)  
response = requests.get(  
  "https://api.speechify.ai/v1/contacts/contact_01jqr8x9zg5k2m3n4p5q6r7s8t",  
  headers={  
    "Authorization": "Bearer "  
  },  
)  
  
print(response.json())
```

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

### Install Speechify SDKs

Source: https://docs.speechify.ai/

Commands to install the official SDKs for Python and TypeScript. Both SDKs automatically authenticate using the SPEECHIFY_API_KEY environment variable.

```bash
pip install speechify-api
```

```bash
npm install @speechify/api
```

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

### Get Route Request

Source: https://docs.speechify.ai/agents/api-reference/v1/apis/-apiId-/routes/-routeId-/get?explorer=true

Example request to retrieve a specific route using the Python requests library.

```python
import requests  
  
# Get Route (GET /v1/apis/:api_id/routes/:route_id)  
response = requests.get(  
  "https://api.speechify.ai/v1/apis/api_01jqr8x9zg5k2m3n4p5q6r7s8t/routes/route_01jqr8x9zg5k2m3n4p5q6r7s8t",  
  headers={  
    "Authorization": "Bearer "  
  },  
)  
  
print(response.json())
```
Tokens:
Raw