Telnyx Ai Inference - curl
Installation
# curl is pre-installed on macOS, Linux, and Windows 10+Setup
export TELNYX_API_KEY="YOUR_API_KEY_HERE"All examples below use $TELNYX_API_KEY for authentication.
Error Handling
All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:
# Check HTTP status code in response
response=$(curl -s -w "\n%{http_code}" \
-X POST "https://api.telnyx.com/v2/messages" \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "+13125550001", "from": "+13125550002", "text": "Hello"}')
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')
case $http_code in
2*) echo "Success: $body" ;;
422) echo "Validation error — check required fields and formats" ;;
429) echo "Rate limited — retry after delay"; sleep 1 ;;
401) echo "Authentication failed — check TELNYX_API_KEY" ;;
*) echo "Error $http_code: $body" ;;
esacCommon error codes: 401 invalid API key, 403 insufficient permissions, 404 resource not found, 422 validation error (check field formats), 429 rate limited (retry with exponential backoff).
Important Notes
- Pagination: List endpoints return paginated results. Use
page[number]andpage[size]query parameters to navigate pages. Checkmeta.total_pagesin the response.
Transcribe speech to text
Transcribe speech to text. This endpoint is consistent with the OpenAI Transcription API and may be used with the OpenAI JS or Python SDK.
POST /ai/audio/transcriptions
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-F "file=@/path/to/file" \
-F "file_url=https://example.com/file.mp3" \
-F "model=distil-whisper/distil-large-v2" \
-F "response_format=json" \
-F "timestamp_granularities[]=segment" \
-F "language=en-US" \
-F "model_config={'smart_format': True, 'punctuate': True}" \
"https://api.telnyx.com/v2/ai/audio/transcriptions"Returns: duration (number), segments (array[object]), text (string)
Create a chat completion
Chat with a language model. This endpoint is consistent with the OpenAI Chat Completions API and may be used with the OpenAI JS or Python SDK.
POST /ai/chat/completions — Required: messages
Optional: api_key_ref (string), best_of (integer), early_stopping (boolean), enable_thinking (boolean), frequency_penalty (number), guided_choice (array[string]), guided_json (object), guided_regex (string), length_penalty (number), logprobs (boolean), max_tokens (integer), min_p (number), model (string), n (number), presence_penalty (number), response_format (object), stream (boolean), temperature (number), tool_choice (enum: none, auto, required), tools (array[object]), top_logprobs (integer), top_p (number), use_beam_search (boolean)
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"role": "system",
"content": "You are a friendly chatbot."
},
{
"role": "user",
"content": "Hello, world!"
}
]
}' \
"https://api.telnyx.com/v2/ai/chat/completions"List conversations
Retrieve a list of all AI conversations configured by the user. Supports PostgREST-style query parameters for filtering. Examples are included for the standard metadata fields, but you can filter on any field in the metadata JSON object.
GET /ai/conversations
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/conversations"Returns: created_at (date-time), id (uuid), last_message_at (date-time), metadata (object), name (string)
Create a conversation
Create a new AI Conversation.
POST /ai/conversations
Optional: metadata (object), name (string)
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
"https://api.telnyx.com/v2/ai/conversations"Returns: created_at (date-time), id (uuid), last_message_at (date-time), metadata (object), name (string)
Get Insight Template Groups
Get all insight groups
GET /ai/conversations/insight-groups
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/conversations/insight-groups"Returns: created_at (date-time), description (string), id (uuid), insights (array[object]), name (string), webhook (string)
Create Insight Template Group
Create a new insight group
POST /ai/conversations/insight-groups — Required: name
Optional: description (string), webhook (string)
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "my-resource"
}' \
"https://api.telnyx.com/v2/ai/conversations/insight-groups"Returns: created_at (date-time), description (string), id (uuid), insights (array[object]), name (string), webhook (string)
Get Insight Template Group
Get insight group by ID
GET /ai/conversations/insight-groups/{group_id}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/conversations/insight-groups/{group_id}"Returns: created_at (date-time), description (string), id (uuid), insights (array[object]), name (string), webhook (string)
Update Insight Template Group
Update an insight template group
PUT /ai/conversations/insight-groups/{group_id}
Optional: description (string), name (string), webhook (string)
curl \
-X PUT \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
"https://api.telnyx.com/v2/ai/conversations/insight-groups/{group_id}"Returns: created_at (date-time), description (string), id (uuid), insights (array[object]), name (string), webhook (string)
Delete Insight Template Group
Delete insight group by ID
DELETE /ai/conversations/insight-groups/{group_id}
curl \
-X DELETE \
-H "Authorization: Bearer $TELNYX_API_KEY" \
"https://api.telnyx.com/v2/ai/conversations/insight-groups/{group_id}"Assign Insight Template To Group
Assign an insight to a group
POST /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/assign
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
"https://api.telnyx.com/v2/ai/conversations/insight-groups/{group_id}/insights/{insight_id}/assign"Unassign Insight Template From Group
Remove an insight from a group
DELETE /ai/conversations/insight-groups/{group_id}/insights/{insight_id}/unassign
curl \
-X DELETE \
-H "Authorization: Bearer $TELNYX_API_KEY" \
"https://api.telnyx.com/v2/ai/conversations/insight-groups/{group_id}/insights/{insight_id}/unassign"Get Insight Templates
Get all insights
GET /ai/conversations/insights
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/conversations/insights"Returns: created_at (date-time), id (uuid), insight_type (enum: custom, default), instructions (string), json_schema (object), name (string), webhook (string)
Create Insight Template
Create a new insight
POST /ai/conversations/insights — Required: instructions, name
Optional: json_schema (object), webhook (string)
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instructions": "You are a helpful assistant.",
"name": "my-resource"
}' \
"https://api.telnyx.com/v2/ai/conversations/insights"Returns: created_at (date-time), id (uuid), insight_type (enum: custom, default), instructions (string), json_schema (object), name (string), webhook (string)
Get Insight Template
Get insight by ID
GET /ai/conversations/insights/{insight_id}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/conversations/insights/{insight_id}"Returns: created_at (date-time), id (uuid), insight_type (enum: custom, default), instructions (string), json_schema (object), name (string), webhook (string)
Update Insight Template
Update an insight template
PUT /ai/conversations/insights/{insight_id}
Optional: instructions (string), json_schema (object), name (string), webhook (string)
curl \
-X PUT \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
"https://api.telnyx.com/v2/ai/conversations/insights/{insight_id}"Returns: created_at (date-time), id (uuid), insight_type (enum: custom, default), instructions (string), json_schema (object), name (string), webhook (string)
Delete Insight Template
Delete insight by ID
DELETE /ai/conversations/insights/{insight_id}
curl \
-X DELETE \
-H "Authorization: Bearer $TELNYX_API_KEY" \
"https://api.telnyx.com/v2/ai/conversations/insights/{insight_id}"Get a conversation
Retrieve a specific AI conversation by its ID.
GET /ai/conversations/{conversation_id}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/conversations/550e8400-e29b-41d4-a716-446655440000"Returns: created_at (date-time), id (uuid), last_message_at (date-time), metadata (object), name (string)
Update conversation metadata
Update metadata for a specific conversation.
PUT /ai/conversations/{conversation_id}
Optional: metadata (object)
curl \
-X PUT \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
"https://api.telnyx.com/v2/ai/conversations/550e8400-e29b-41d4-a716-446655440000"Returns: created_at (date-time), id (uuid), last_message_at (date-time), metadata (object), name (string)
Delete a conversation
Delete a specific conversation by its ID.
DELETE /ai/conversations/{conversation_id}
curl \
-X DELETE \
-H "Authorization: Bearer $TELNYX_API_KEY" \
"https://api.telnyx.com/v2/ai/conversations/550e8400-e29b-41d4-a716-446655440000"Get insights for a conversation
Retrieve insights for a specific conversation
GET /ai/conversations/{conversation_id}/conversations-insights
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/conversations/550e8400-e29b-41d4-a716-446655440000/conversations-insights"Returns: conversation_insights (array[object]), created_at (date-time), id (string), status (enum: pending, in_progress, completed, failed)
Create Message
Add a new message to the conversation. Used to insert a new messages to a conversation manually (without using chat endpoint)
POST /ai/conversations/{conversation_id}/message — Required: role
Optional: content (string), metadata (object), name (string), sent_at (date-time), tool_call_id (string), tool_calls (array[object]), tool_choice (object)
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"role": "user"
}' \
"https://api.telnyx.com/v2/ai/conversations/550e8400-e29b-41d4-a716-446655440000/message"Get conversation messages
Retrieve messages for a specific conversation, including tool calls made by the assistant.
GET /ai/conversations/{conversation_id}/messages
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/conversations/550e8400-e29b-41d4-a716-446655440000/messages"Returns: created_at (date-time), role (enum: user, assistant, tool), sent_at (date-time), text (string), tool_calls (array[object])
Get Tasks by Status
Retrieve tasks for the user that are either queued, processing, failed, success or partial_success based on the query string. Defaults to queued and processing.
GET /ai/embeddings
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/embeddings"Returns: bucket (string), created_at (date-time), finished_at (date-time), status (enum: queued, processing, success, failure, partial_success), task_id (string), task_name (string), user_id (string)
Embed documents
Perform embedding on a Telnyx Storage Bucket using an embedding model. The current supported file types are:
- HTML
- txt/unstructured text files
- json
- csv
- audio / video (mp3, mp4, mpeg, mpga, m4a, wav, or webm) - Max of 100mb file size. Any files not matching the above types will be attempted to be embedded as unstructured text.
POST /ai/embeddings — Required: bucket_name
Optional: document_chunk_overlap_size (integer), document_chunk_size (integer), embedding_model (object), loader (object)
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"bucket_name": "my-bucket"
}' \
"https://api.telnyx.com/v2/ai/embeddings"Returns: created_at (string), finished_at (string | null), status (string), task_id (uuid), task_name (string), user_id (uuid)
List embedded buckets
Get all embedding buckets for a user.
GET /ai/embeddings/buckets
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/embeddings/buckets"Returns: buckets (array[string])
Get file-level embedding statuses for a bucket
Get all embedded files for a given user bucket, including their processing status.
GET /ai/embeddings/buckets/{bucket_name}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/embeddings/buckets/{bucket_name}"Returns: created_at (date-time), error_reason (string), filename (string), last_embedded_at (date-time), status (string), updated_at (date-time)
Disable AI for an Embedded Bucket
Deletes an entire bucket's embeddings and disables the bucket for AI-use, returning it to normal storage pricing.
DELETE /ai/embeddings/buckets/{bucket_name}
curl \
-X DELETE \
-H "Authorization: Bearer $TELNYX_API_KEY" \
"https://api.telnyx.com/v2/ai/embeddings/buckets/{bucket_name}"Search for documents
Perform a similarity search on a Telnyx Storage Bucket, returning the most similar num_docs document chunks to the query. Currently the only available distance metric is cosine similarity which will return a distance between 0 and 1. The lower the distance, the more similar the returned document chunks are to the query.
POST /ai/embeddings/similarity-search — Required: bucket_name, query
Optional: num_of_docs (integer)
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"bucket_name": "my-bucket",
"query": "What is Telnyx?"
}' \
"https://api.telnyx.com/v2/ai/embeddings/similarity-search"Returns: distance (number), document_chunk (string), metadata (object)
Embed URL content
Embed website content from a specified URL, including child pages up to 5 levels deep within the same domain. The process crawls and loads content from the main URL and its linked pages into a Telnyx Cloud Storage bucket.
POST /ai/embeddings/url — Required: url, bucket_name
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/resource",
"bucket_name": "my-bucket"
}' \
"https://api.telnyx.com/v2/ai/embeddings/url"Returns: created_at (string), finished_at (string | null), status (string), task_id (uuid), task_name (string), user_id (uuid)
Get an embedding task's status
Check the status of a current embedding task. Will be one of the following:
queued- Task is waiting to be picked up by a workerprocessing- The embedding task is runningsuccess- Task completed successfully and the bucket is embeddedfailure- Task failed and no files were embedded successfullypartial_success- Some files were embedded successfully, but at least one failed
GET /ai/embeddings/{task_id}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/embeddings/{task_id}"Returns: created_at (string), finished_at (string), status (enum: queued, processing, success, failure, partial_success), task_id (uuid), task_name (string)
List fine tuning jobs
Retrieve a list of all fine tuning jobs created by the user.
GET /ai/fine_tuning/jobs
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/fine_tuning/jobs"Returns: created_at (integer), finished_at (integer | null), hyperparameters (object), id (string), model (string), organization_id (string), status (enum: queued, running, succeeded, failed, cancelled), trained_tokens (integer | null), training_file (string)
Create a fine tuning job
Create a new fine tuning job.
POST /ai/fine_tuning/jobs — Required: model, training_file
Optional: hyperparameters (object), suffix (string)
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o",
"training_file": "training-data.jsonl"
}' \
"https://api.telnyx.com/v2/ai/fine_tuning/jobs"Returns: created_at (integer), finished_at (integer | null), hyperparameters (object), id (string), model (string), organization_id (string), status (enum: queued, running, succeeded, failed, cancelled), trained_tokens (integer | null), training_file (string)
Get a fine tuning job
Retrieve a fine tuning job by job_id.
GET /ai/fine_tuning/jobs/{job_id}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/fine_tuning/jobs/{job_id}"Returns: created_at (integer), finished_at (integer | null), hyperparameters (object), id (string), model (string), organization_id (string), status (enum: queued, running, succeeded, failed, cancelled), trained_tokens (integer | null), training_file (string)
Cancel a fine tuning job
Cancel a fine tuning job.
POST /ai/fine_tuning/jobs/{job_id}/cancel
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
"https://api.telnyx.com/v2/ai/fine_tuning/jobs/{job_id}/cancel"Returns: created_at (integer), finished_at (integer | null), hyperparameters (object), id (string), model (string), organization_id (string), status (enum: queued, running, succeeded, failed, cancelled), trained_tokens (integer | null), training_file (string)
Get available models
This endpoint returns a list of Open Source and OpenAI models that are available for use. Note: Model id's will be in the form {source}/{model_name}. For example openai/gpt-4 or mistralai/Mistral-7B-Instruct-v0.1 consistent with HuggingFace naming conventions.
GET /ai/models
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/models"Returns: created (integer), id (string), object (string), owned_by (string)
Create embeddings
Creates an embedding vector representing the input text. This endpoint is compatible with the OpenAI Embeddings API and may be used with the OpenAI JS or Python SDK by setting the base URL to https://api.telnyx.com/v2/ai/openai.
POST /ai/openai/embeddings — Required: input, model
Optional: dimensions (integer), encoding_format (enum: float, base64), user (string)
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": "The quick brown fox jumps over the lazy dog",
"model": "thenlper/gte-large"
}' \
"https://api.telnyx.com/v2/ai/openai/embeddings"Returns: data (array[object]), model (string), object (string), usage (object)
List embedding models
Returns a list of available embedding models. This endpoint is compatible with the OpenAI Models API format.
GET /ai/openai/embeddings/models
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/ai/openai/embeddings/models"Returns: created (integer), id (string), object (string), owned_by (string)
Summarize file content
Generate a summary of a file's contents. Supports the following text formats:
- PDF, HTML, txt, json, csv
Supports the following media formats (billed for both the transcription and summary):
- flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm
- Up to 100 MB
POST /ai/summarize — Required: bucket, filename
Optional: system_prompt (string)
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"bucket": "my-bucket",
"filename": "data.csv"
}' \
"https://api.telnyx.com/v2/ai/summarize"Returns: summary (string)
Get all Speech to Text batch report requests
Retrieves all Speech to Text batch report requests for the authenticated user
GET /legacy/reporting/batch_detail_records/speech_to_text
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/legacy/reporting/batch_detail_records/speech_to_text"Returns: created_at (date-time), download_link (string), end_date (date-time), id (string), record_type (string), start_date (date-time), status (enum: PENDING, COMPLETE, FAILED, EXPIRED)
Create a new Speech to Text batch report request
Creates a new Speech to Text batch report request with the specified filters
POST /legacy/reporting/batch_detail_records/speech_to_text — Required: start_date, end_date
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"start_date": "2020-07-01T00:00:00-06:00",
"end_date": "2020-07-01T00:00:00-06:00"
}' \
"https://api.telnyx.com/v2/legacy/reporting/batch_detail_records/speech_to_text"Returns: created_at (date-time), download_link (string), end_date (date-time), id (string), record_type (string), start_date (date-time), status (enum: PENDING, COMPLETE, FAILED, EXPIRED)
Get a specific Speech to Text batch report request
Retrieves a specific Speech to Text batch report request by ID
GET /legacy/reporting/batch_detail_records/speech_to_text/{id}
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/legacy/reporting/batch_detail_records/speech_to_text/550e8400-e29b-41d4-a716-446655440000"Returns: created_at (date-time), download_link (string), end_date (date-time), id (string), record_type (string), start_date (date-time), status (enum: PENDING, COMPLETE, FAILED, EXPIRED)
Delete a Speech to Text batch report request
Deletes a specific Speech to Text batch report request by ID
DELETE /legacy/reporting/batch_detail_records/speech_to_text/{id}
curl \
-X DELETE \
-H "Authorization: Bearer $TELNYX_API_KEY" \
"https://api.telnyx.com/v2/legacy/reporting/batch_detail_records/speech_to_text/550e8400-e29b-41d4-a716-446655440000"Returns: created_at (date-time), download_link (string), end_date (date-time), id (string), record_type (string), start_date (date-time), status (enum: PENDING, COMPLETE, FAILED, EXPIRED)
Get speech to text usage report
Generate and fetch speech to text usage report synchronously. This endpoint will both generate and fetch the speech to text report over a specified time period.
GET /legacy/reporting/usage_reports/speech_to_text
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/legacy/reporting/usage_reports/speech_to_text?start_date=2020-07-02T00:00:00-06:00&end_date=2020-07-01T00:00:00-06:00"Returns: data (object)
Speech to text over WebSocket
Open a WebSocket connection to stream audio and receive transcriptions in real-time. Authentication is provided via the standard Authorization: Bearer header. Supported engines: Azure, Deepgram, Google, Telnyx.
GET /speech-to-text/transcription
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/speech-to-text/transcription?transcription_engine=Telnyx&input_format=mp3&language=en-US&interim_results=True&endpointing=500&redact=pci&keyterm=Telnyx&keywords=Telnyx,SIP,WebRTC"Stream text to speech over WebSocket
Open a WebSocket connection to stream text and receive synthesized audio in real time. Authentication is provided via the standard Authorization: Bearer header. Send JSON frames with text to synthesize; receive JSON frames containing base64-encoded audio chunks.
GET /text-to-speech/speech
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/text-to-speech/speech"Generate speech from text
Generate synthesized speech audio from text input. Returns audio in the requested format (binary audio stream, base64-encoded JSON, or an audio URL for later retrieval). Authentication is provided via the standard Authorization: Bearer header.
POST /text-to-speech/speech
Optional: aws (object), azure (object), disable_cache (boolean), elevenlabs (object), language (string), minimax (object), output_type (enum: binary_output, base64_output), provider (enum: aws, telnyx, azure, elevenlabs, minimax, rime, resemble), resemble (object), rime (object), telnyx (object), text (string), text_type (enum: text, ssml), voice (string), voice_settings (object)
curl \
-X POST \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
"https://api.telnyx.com/v2/text-to-speech/speech"Returns: base64_audio (string)
List available voices
Retrieve a list of available voices from one or all TTS providers. When provider is specified, returns voices for that provider only. Otherwise, returns voices from all providers.
GET /text-to-speech/voices
curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/text-to-speech/voices"Returns: voices (array[object])