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
text

Authentication

All API endpoints require authentication using the X-API-Key header:
X-API-Key: YOUR_API_KEY
text
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
}
}
json

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'
bash

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": "ሰላም እንዴት ነህ?"
}
json
| 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
}
json

Non-streaming Response

{
"audio": "base64-encoded-audio-data"
}
json
| 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}
...
text
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.):
  1. Add attachment fields in the multipart request
  2. 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" # Replace with your actual 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
}
}
# Add conversation history if provided
if conversation_history:
data["conversation_history"] = conversation_history
# For non-streaming requests
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
# For streaming requests
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')
# Skip the "data: " prefix in SSE
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
# Example usage - Non-streaming
response = chat_generate(
prompt="What is the capital of Ethiopia?",
target_language="am"
)
if response:
print(response["response_text"])
# Example usage - Streaming
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)
# Check if this is the last chunk
if "finish_reason" in chunk or "is_last_chunk" in chunk:
print("\nStream finished.")
python

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" # Replace with your actual API key
url = "https://api.addisassistant.com/api/v1/chat_generate"
headers = {
"X-API-Key": api_key
}
# Create the JSON part of the request
request_data = {
"prompt": prompt,
"target_language": target_language,
"attachment_field_names": ["image1"]
}
# Create multipart form data
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
# Example usage
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"])
python

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" # Replace with your actual 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
}
# For non-streaming requests
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:
# Decode base64 audio
audio_bytes = base64.b64decode(response_data["audio"])
return audio_bytes
else:
print(f"Error: {response.status_code}")
print(response.text)
return None
# For streaming requests
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:
# Decode base64 chunk
chunk_bytes = base64.b64decode(line_data["audio_chunk"])
audio_chunks.append(chunk_bytes)
yield chunk_bytes
# You can also return the combined audio if needed
# return b''.join(audio_chunks)
else:
print(f"Error: {response.status_code}")
print(response.text)
return None
# Example usage - Non-streaming
audio_data = text_to_speech(
text="ሰላም ፣ እንደምን ነህ?",
language="am"
)
if audio_data:
# Save to file
with open("output.wav", "wb") as f:
f.write(audio_data)
# Or play directly if pydub is installed
try:
audio = AudioSegment.from_file(io.BytesIO(audio_data), format="wav")
play(audio)
except:
print("Saved audio to output.wav")
# Example usage - Streaming
audio_chunks = []
for chunk in text_to_speech(
text="ሰላም ፣ እንደምን ነህ? ይህ ትንሽ ረጅም ቃል ነው...",
language="am",
stream=True
):
audio_chunks.append(chunk)
# Process chunks as they arrive
print("Received audio chunk")
# Combine all chunks when complete
if audio_chunks:
complete_audio = b''.join(audio_chunks)
with open("output_stream.wav", "wb") as f:
f.write(complete_audio)
python