API Keys

Valuez AI exposes a single orchestrator endpoint that handles all four integration modes - Text to Text, Speech to Text, Text to Speech, and Speech to Speech. Your API key and the connectionType parameter determine how each request is processed. All requests go to: https://api.dashboard.valuez.ai Authentication uses the x-api-key header. See Authentication for details on key types and security practices.

Agent Chat API

Endpoint: POST /api/v1/external/chat All four agent interaction modes use this single endpoint. The connectionType parameter tells the orchestrator how to handle the request.

Common Headers

Every request to this endpoint requires:

Header	Value
`x-api-key`	Your Agent API key (`valuezai_api_...` or `wow_api_...`)
`Content-Type`	`application/json` (or `multipart/form-data` when uploading audio files)

Mode 1 - Text to Text (TTT)

Send a text message to your agent and receive a text response. Use this for chat interfaces, CRM integrations, and any text-based interaction.

Synchronous Response

Returns the full answer in a single JSON response.

cURL

curl -X POST "https://api.dashboard.valuez.ai/api/v1/external/chat" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "connectionType": "ttt",
    "responseMode": "sync",
    "question": "Hello, tell me about your services.",
    "sessionUUID": null,
    "variables": {}
  }'

Streaming Response

Streams the answer chunk by chunk using Server-Sent Events (SSE). Use this for real-time chat interfaces where you want to display text as it is generated.

cURL

curl -X POST "https://api.dashboard.valuez.ai/api/v1/external/chat" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "connectionType": "ttt",
    "responseMode": "stream",
    "question": "Write a long paragraph about coding."
  }'

TTT Parameters

Parameter	Type	Required	Description
`connectionType`	string	✅	Must be `"ttt"`
`responseMode`	string	✅	`"sync"` for full response, `"stream"` for SSE streaming
`question`	string	✅	The text message to send to the agent
`sessionUUID`	string	❌	Pass a previous session UUID to continue a conversation. Pass `null` to start a new one
`variables`	object	❌	Optional key-value pairs passed to the agent

Mode 2 - Speech to Text (STT)

Send an audio file to the agent. The platform transcribes the audio, runs it through the agent, and returns both the transcription and the agent’s text response.

Option A - Upload a Binary Audio File

cURL

curl -X POST "https://api.dashboard.valuez.ai/api/v1/external/chat" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -F "audioFile=@/path/to/user_recording.wav" \
  -F "sessionUUID="

When uploading a file using multipart/form-data, the system automatically detects the audio and sets connectionType to "stt". Do not set Content-Type: application/json for file uploads.

Option B - Pass Base64 Encoded Audio

cURL

curl -X POST "https://api.dashboard.valuez.ai/api/v1/external/chat" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "connectionType": "stt",
    "input": {
      "audioBase64": "UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
    }
  }'

Mode 3 - Text to Speech (TTS)

Send a text question to the agent and receive the agent’s response as a synthesized WAV audio file instead of text. Use this when you need to play the agent’s response through a speaker or phone system.

cURL

curl -X POST "https://api.dashboard.valuez.ai/api/v1/external/chat" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "connectionType": "tts",
    "question": "Can you speak this answer back to me?",
    "sessionUUID": null
  }' \
  --output agent_response.wav

The session UUID for continuing the conversation is returned in the response header X-Session-UUID. Store this value and pass it in subsequent requests to maintain conversation context.

Mode 4 - Speech to Speech (STS)

Initializes a real-time voice session. Since HTTP is not suitable for duplex real-time streaming, this endpoint returns a WebSocket URL that you connect to for the live voice conversation.

cURL

curl -X POST "https://api.dashboard.valuez.ai/api/v1/external/chat" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "connectionType": "sts",
    "responseMode": "realtime",
    "sessionUUID": null,
    "variables": {}
  }'

Example Response:

{
  "statusCode": 200,
  "sessionUUID": "a5e971cf-cb52-4754-b631-01df82a7f502",
  "connectionType": "sts",
  "wsUrl": "wss://api.dashboard.valuez.ai/ws/sts",
  "message": "Connect to the provided wsUrl to begin the realtime session..."
}

Connect to the wsUrl using a WebSocket client to begin the real-time voice session.

Mode Comparison

Mode	Input	Output	Best For
TTT	Text	Text	Chat interfaces, CRM bots, text automation
STT	Audio file	Text	Voice recordings, transcription workflows
TTS	Text	Audio (WAV)	Phone systems, audio playback
STS	Real-time voice	Real-time voice	Live voice agents, phone calls

STT/TTS External API

These endpoints give you direct access to Valuez AI’s speech processing infrastructure - independent of any agent. Use your STT/TTS API key (ext_api_...) for these requests.

Text to Speech (TTS)

Convert any text string into a WAV audio file. Endpoint: POST /api/v1/tts/external

cURL

curl -X POST "https://api.dashboard.valuez.ai/api/v1/tts/external" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_EXTERNAL_API_KEY_HERE" \
  -d '{
    "text": "Welcome to Valuez AI. How can I help you today?",
    "language": "english",
    "pace": 1.0,
    "pitch": 1.0,
    "volume": 1.0
  }' \
  --output response_speech.wav

Parameters:

Parameter	Type	Required	Description
`text`	string	✅	The text to convert to speech
`language`	string	✅	`"english"`, `"hindi"`, or `"marathi"`
`pace`	float	❌	Speech speed. `1.0` is normal. Lower is slower, higher is faster
`pitch`	float	❌	Voice pitch. `1.0` is normal
`volume`	float	❌	Audio volume. `1.0` is normal

Speech to Text (STT)

Convert an audio file into a text transcription. Endpoint: POST /api/v1/stt/external

cURL

curl -X POST "https://api.dashboard.valuez.ai/api/v1/stt/external?language=english" \
  -H "x-api-key: YOUR_EXTERNAL_API_KEY_HERE" \
  -F "audioFile=@/path/to/your/audio.wav"

Query Parameters:

Parameter	Type	Required	Description
`language`	string	✅	`"english"`, `"hindi"`, or `"marathi"`

Supported languages: english, hindi, marathi

Generating Your API Keys

API keys are generated from the Integrations section of your dashboard - not from Settings. See Integrations for step-by-step instructions on creating:

Agent API keys for the /api/v1/external/chat endpoint
STT/TTS API keys for the /api/v1/tts/external and /api/v1/stt/external endpoints

Next Steps

Integrations

Generate your API keys and configure endpoint access for your integration.

Authentication

Learn about the x-api-key header and security best practices.

API Logs

Monitor all STT/TTS API calls - usage, latency, and transcriptions.

Agents

Configure the agent your API key is connected to.

Getting Started

Core Concepts

Voice Calling

Platform

Account

Agent Chat API

Common Headers

Mode 1 - Text to Text (TTT)

Synchronous Response

Streaming Response

TTT Parameters

Mode 2 - Speech to Text (STT)

Option A - Upload a Binary Audio File

Option B - Pass Base64 Encoded Audio

Mode 3 - Text to Speech (TTS)

Mode 4 - Speech to Speech (STS)

Mode Comparison

STT/TTS External API

Text to Speech (TTS)

Speech to Text (STT)

Generating Your API Keys

Next Steps

Integrations

Authentication

API Logs

Agents

​Agent Chat API

​Common Headers

​Mode 1 - Text to Text (TTT)

​Synchronous Response

​Streaming Response

​TTT Parameters

​Mode 2 - Speech to Text (STT)

​Option A - Upload a Binary Audio File

​Option B - Pass Base64 Encoded Audio

​Mode 3 - Text to Speech (TTS)

​Mode 4 - Speech to Speech (STS)

​Mode Comparison

​STT/TTS External API

​Text to Speech (TTS)

​Speech to Text (STT)

​Generating Your API Keys

​Next Steps

Integrations

Authentication

API Logs

Agents

Agent Chat API

Common Headers

Mode 1 - Text to Text (TTT)

Synchronous Response

Streaming Response

TTT Parameters

Mode 2 - Speech to Text (STT)

Option A - Upload a Binary Audio File

Option B - Pass Base64 Encoded Audio

Mode 3 - Text to Speech (TTS)

Mode 4 - Speech to Speech (STS)

Mode Comparison

STT/TTS External API

Text to Speech (TTS)

Speech to Text (STT)

Generating Your API Keys

Next Steps