API reference / AI utilities
AI utilities
The AI utilities endpoints of the Voiceland AI API, with parameters, schemas and curl examples.
Last updated:
POST /v1/chat#
Ask a question over a transcript. Answers a question about a transcript. freeform returns an answer; structured also returns matched + a summary.
Request body
application/json Schema: ChatRequest
| Field | Type | Required | Description |
|---|---|---|---|
history |
array of ChatMessage |
Optional prior turns for multi-turn context. | |
max_tokens |
integer | Optional cap on the response length. | |
mode |
string | Yes | freeform (default) returns an answer; structured also returns matched + a summary. |
model |
string | Optional model override from the account catalog. | |
question |
string | Yes | The question to answer about the transcript. |
transcript |
string | Yes | The conversation text to reason over. |
Responses
| Code | Description |
|---|---|
200 |
Success. |
401 |
Missing or invalid API key. |
4XX |
Request error (validation, not-found, etc.). |
5XX |
Server or upstream error. |
Example request
curl -X POST "https://api.voiceland.ai/v1/chat" \
-H "Authorization: Bearer VL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "structured",
"question": "What order number?",
"transcript": "caller: cancel order 4471\nagent: done."
}'A successful response returns a StructuredResponse.
Example response
{
"answer": "4471",
"matched": true,
"summary": "Caller cancelled order 4471."
}POST /v1/transcribe#
Transcribe audio. Transcribes an uploaded audio file. Send multipart/form-data with a file part; optional language, model, and speaker_diarization fields.
Request body
multipart/form-data
Responses
| Code | Description |
|---|---|
200 |
Success. |
401 |
Missing or invalid API key. |
4XX |
Request error (validation, not-found, etc.). |
5XX |
Server or upstream error. |
Example request
curl -X POST "https://api.voiceland.ai/v1/transcribe" \
-H "Authorization: Bearer VL_API_KEY" \
-F "file=@audio.wav" \
-F "language=el" \
-F "speaker_diarization=true"Example response
{
"audio_duration_seconds": 12.3,
"language": "el",
"text": "Καλησπέρα…",
"transcription_id": "…"
}Schemas#
ChatMessage#
| Field | Type | Required | Description |
|---|---|---|---|
content |
string | Yes | |
role |
string | Yes |
ChatRequest#
Ask a question over a transcript.
| Field | Type | Required | Description |
|---|---|---|---|
history |
array of ChatMessage |
Optional prior turns for multi-turn context. | |
max_tokens |
integer | Optional cap on the response length. | |
mode |
string | Yes | freeform (default) returns an answer; structured also returns matched + a summary. |
model |
string | Optional model override from the account catalog. | |
question |
string | Yes | The question to answer about the transcript. |
transcript |
string | Yes | The conversation text to reason over. |
ChatUsage#
| Field | Type | Required | Description |
|---|---|---|---|
completion_tokens |
integer | Yes | |
prompt_tokens |
integer | Yes | |
total_tokens |
integer | Yes |
Error#
Error envelope returned for non-2xx responses.
| Field | Type | Required | Description |
|---|---|---|---|
error |
object | Yes |
StructuredResponse#
| Field | Type | Required | Description |
|---|---|---|---|
answer |
string | Yes | The extracted answer. |
matched |
boolean | Yes | Whether the transcript contained an answer. |
model |
string | Yes | |
summary |
string | Yes | A short summary of the transcript. |
usage |
ChatUsage |
Yes |