API Endpoints Reference
This page provides detailed information about all available endpoints in the Addis AI API.
Base URL
All API requests should be made to:
https://api.addisassistant.com
Authentication
All API endpoints require authentication using the
X-API-Key
header:
Replace
YOUR_API_KEY
with your actual API key.
Available Endpoints
Chat Generation
POST /chat_generate
The primary endpoint for generating text responses from the Addis AI model. This endpoint supports both text-only and multi-modal inputs.
Request Methods
- Content-Type:
application/json
(for text-only requests)
- Content-Type:
multipart/form-data
(for requests with images, audio, or other attachments)
Request Parameters (JSON)
| Parameter | Type | Required | Description |
| ------------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
|
prompt
| string | Yes | The text prompt or question to send to the model |
|
target_language
| string | Yes | The target language for the response (
"am"
for Amharic,
"om"
for Afan Oromo) |
|
conversation_history
| array | No | Array of previous messages for context (see
Conversation Management) |
|
generation_config
| object | No | Configuration options for text generation |
|
attachment_field_names
| array | No | Names of attachment fields in
multipart/form-data
requests |
generation_config
Object
| Parameter | Type | Default | Description |
| ----------------- | ------- | ------------- | -------------------------------------------------------------------- |
|
temperature
| number |
0.7
| Controls randomness/creativity of the response (0.0-1.0) |
|
stream
| boolean |
false
| Whether to stream the response incrementally (BETA feature for chat) |
|
maxOutputTokens
| number | Model default | Maximum number of tokens to generate |
Request Example (Text-only)
{
"prompt": "What is the capital of Ethiopia?",
"target_language": "am",
"generation_config": {
"temperature": 0.7,
"maxOutputTokens": 1200,
"stream": false
}
}
Request Example (Multipart with Image)
For multipart requests, all JSON parameters must be included within a field named
request_data
:
curl -X POST https://api.addisassistant.com/api/v1/chat_generate \
-H "X-API-Key: YOUR_API_KEY" \
-F "image1=@/path/to/image.jpg" \
-F 'request_data={
"prompt": "Describe this image",
"target_language": "am",
"attachment_field_names": ["image1"]
};type=application/json'
Response Format
{
"response_text": "Addis Ababa is the capital of Ethiopia.",
"finish_reason": "stop",
"usage_metadata": {
"prompt_token_count": 12,
"candidates_token_count": 8,
"total_token_count": 20
},
"modelVersion": "Addis-፩-አሌፍ",
"uploaded_attachments": [],
"transcription_raw": "<analysis>gender: male, emotion: happy</analysis> ሰላም እንዴት ነህ?",
"transcription_clean": "ሰላም እንዴት ነህ?"
}
| Response Field | Type | Description |
| ---------------------- | ------ | -------------------------------------------------------------------- |
|
response_text
| string | The generated text response from the model |
|
finish_reason
| string | Reason why the response ended (e.g., "stop", "length", etc.) |
|
usage_metadata
| object | Token usage information for the request |
|
modelVersion
| string | Version of the model used for generation |
|
uploaded_attachments
| array | Information about any uploaded attachments (URIs, MIME types) |
|
transcription_raw
| string | Raw transcription with analysis (only present for audio inputs) |
|
transcription_clean
| string | Clean transcription without analysis (only present for audio inputs) |
Audio (Text-to-Speech)
POST /audio
Converts text to natural-sounding speech in Amharic or Afan Oromo.
Request Parameters
| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | -------------------------------------------------------------------- |
|
text
| string | Yes | The text to convert to speech |
|
language
| string | Yes | The language of the text (
"am"
for Amharic,
"om"
for Afan Oromo) |
|
stream
| boolean | No | Whether to stream the audio response in chunks (default:
false
) |
Request Example
{
"text": "ሰላም ፣ እንደምን ነህ?",
"language": "am",
"stream": false
}
Non-streaming Response
{
"audio": "base64-encoded-audio-data"
}
| Response Field | Type | Description |
| -------------- | ------ | -------------------------------------------------- |
|
audio
| string | Base64-encoded WAV audio of the synthesized speech |
Streaming Response
When
stream
is
true
, the response is sent as a series of line-delimited JSON objects:
{"audio_chunk": "base64-encoded-chunk", "index": 0}
{"audio_chunk": "base64-encoded-chunk", "index": 1}
...
Each chunk contains a portion of the audio and an index indicating its position in the sequence.
Input Types for Chat API
The
/chat_generate
endpoint supports multiple input methods:
1. Text-only Input
Use a standard JSON request with text in the
prompt
field.
2. Audio-only Input
Submit audio via
multipart/form-data
with a field named
chat_audio_input
. The API will transcribe the audio and use it as the prompt.
Supported audio formats:
- WAV:
audio/wav
, audio/x-wav
, audio/wave
, audio/x-pn-wav
- MP3:
audio/mpeg
, audio/mp3
, audio/x-mp3
- M4A/MP4:
audio/mp4
, audio/x-m4a
, audio/m4a
- WebM/Ogg/FLAC:
audio/webm
, audio/ogg
, audio/x-flac
, audio/flac
3. Combined Text and Audio
You can include both text and audio in the same request by including both the
chat_audio_input
field and a
prompt
field in the
request_data
JSON.
4. With Attachments
To include file attachments (images, documents, etc.):
- Add attachment fields in the multipart request
- List their field names in the
attachment_field_names
array in the request_data
JSON
Important Format Differences
- For JSON requests (Content-Type: application/json): Parameters like
prompt
are sent directly in the JSON body
- For multipart/form-data requests: ALL JSON parameters must be wrapped inside a field named
request_data
Python Examples
Basic Chat Request
import requests
import json
def chat_generate(prompt, target_language, conversation_history=None, stream=False):
"""
Send a text-only request to the Addis AI chat_generate endpoint.
Args:
prompt (str): The text prompt or question
target_language (str): "am" for Amharic or "om" for Afan Oromo
conversation_history (list, optional): Previous conversation messages
stream (bool, optional): Whether to use streaming responses
Returns:
dict: The API response
"""
api_key = "YOUR_API_KEY"
url = "https://api.addisassistant.com/api/v1/chat_generate"
headers = {
"X-API-Key": api_key,
"Content-Type": "application/json"
}
data = {
"prompt": prompt,
"target_language": target_language,
"generation_config": {
"temperature": 0.7,
"stream": stream
}
}
if conversation_history:
data["conversation_history"] = conversation_history
if not stream:
response = requests.post(url, headers=headers, json=data)
if response.status_code == 200:
return response.json()
else:
print(f"Error: {response.status_code}")
print(response.text)
return None
else:
response = requests.post(url, headers=headers, json=data, stream=True)
if response.status_code == 200:
for line in response.iter_lines():
if line:
line = line.decode('utf-8')
if line.startswith('data: '):
try:
chunk = json.loads(line[6:])
yield chunk
except json.JSONDecodeError:
print(f"Error parsing JSON: {line}")
else:
print(f"Error: {response.status_code}")
print(response.text)
return None
response = chat_generate(
prompt="What is the capital of Ethiopia?",
target_language="am"
)
if response:
print(response["response_text"])
for chunk in chat_generate(
prompt="Tell me a long story about Ethiopia",
target_language="am",
stream=True
):
if "response_text" in chunk:
print(chunk["response_text"], end="", flush=True)
if "finish_reason" in chunk or "is_last_chunk" in chunk:
print("\nStream finished.")
Multi-modal Request with Image
import requests
import json
import os
def chat_with_image(prompt, image_path, target_language):
"""
Send a request with text and image to the Addis AI chat_generate endpoint.
Args:
prompt (str): The text prompt or question
image_path (str): Path to the image file
target_language (str): "am" for Amharic or "om" for Afan Oromo
Returns:
dict: The API response
"""
api_key = "YOUR_API_KEY"
url = "https://api.addisassistant.com/api/v1/chat_generate"
headers = {
"X-API-Key": api_key
}
request_data = {
"prompt": prompt,
"target_language": target_language,
"attachment_field_names": ["image1"]
}
files = {
"request_data": (None, json.dumps(request_data), "application/json"),
"image1": (os.path.basename(image_path), open(image_path, "rb"), "image/jpeg")
}
response = requests.post(url, headers=headers, files=files)
if response.status_code == 200:
return response.json()
else:
print(f"Error: {response.status_code}")
print(response.text)
return None
response = chat_with_image(
prompt="What's in this image?",
image_path="/path/to/your/image.jpg",
target_language="am"
)
if response:
print(response["response_text"])
Text-to-Speech Request
import requests
import json
import base64
import io
from pydub import AudioSegment
from pydub.playback import play
def text_to_speech(text, language, stream=False):
"""
Convert text to speech using the Addis AI audio endpoint.
Args:
text (str): The text to convert to speech
language (str): "am" for Amharic or "om" for Afan Oromo
stream (bool, optional): Whether to use streaming responses
Returns:
bytes: The audio data or None if error
"""
api_key = "YOUR_API_KEY"
url = "https://api.addisassistant.com/api/v1/audio"
headers = {
"X-API-Key": api_key,
"Content-Type": "application/json"
}
data = {
"text": text,
"language": language,
"stream": stream
}
if not stream:
response = requests.post(url, headers=headers, json=data)
if response.status_code == 200:
response_data = response.json()
if "audio" in response_data:
audio_bytes = base64.b64decode(response_data["audio"])
return audio_bytes
else:
print(f"Error: {response.status_code}")
print(response.text)
return None
else:
response = requests.post(url, headers=headers, json=data, stream=True)
if response.status_code == 200:
audio_chunks = []
for line in response.iter_lines():
if line:
line_data = json.loads(line)
if "audio_chunk" in line_data:
chunk_bytes = base64.b64decode(line_data["audio_chunk"])
audio_chunks.append(chunk_bytes)
yield chunk_bytes
else:
print(f"Error: {response.status_code}")
print(response.text)
return None
audio_data = text_to_speech(
text="ሰላም ፣ እንደምን ነህ?",
language="am"
)
if audio_data:
with open("output.wav", "wb") as f:
f.write(audio_data)
try:
audio = AudioSegment.from_file(io.BytesIO(audio_data), format="wav")
play(audio)
except:
print("Saved audio to output.wav")
audio_chunks = []
for chunk in text_to_speech(
text="ሰላም ፣ እንደምን ነህ? ይህ ትንሽ ረጅም ቃል ነው...",
language="am",
stream=True
):
audio_chunks.append(chunk)
print("Received audio chunk")
if audio_chunks:
complete_audio = b''.join(audio_chunks)
with open("output_stream.wav", "wb") as f:
f.write(complete_audio)