Addis AI Logo

Quick Start Guide

This guide provides essential information to quickly begin working with the Addis AI API.

Authentication

All API requests require authentication via the X-API-Key header: 
X-API-Key: YOUR_API_KEY
bash

Base URLs and Endpoints

Base URLs

Production:
  • https://api.addisassistant.com

Primary Endpoints

The API provides two main endpoints: | Endpoint | Description | Method | | ---------------- | --------------------------------- | ------ | | /chat_generate | Text generation and conversations | POST | | /audio | Text-to-speech conversion | POST |

Basic Request Examples

Text Generation (Chat)

curl -X POST https://api.addisassistant.com/api/v1/chat_generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "ኢትዮጵያ ዋና ከተማ ማን ናት?",
    "target_language": "am"
  }'
bash
Sample Response: 
{
  "response_text": "የኢትዮጵያ ዋና ከተማ አዲስ አበባ ናት።",
  "finish_reason": "stop",
  "usage_metadata": {
    "prompt_token_count": 10,
    "candidates_token_count": 12,
    "total_token_count": 22
  },
  "modelVersion": "Addis-፩-አሌፍ"
}
json

Text-to-Speech (Audio)

curl -X POST https://api.addisassistant.com/api/v1/audio \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "ሰላም፡ ይህ የእኔ ድምፅ ነው።",
    "language": "am"
  }'
bash
Sample Response: 
{
  "audio": "data:audio/wav;base64,UklGRiQg..."
}
json
The audio field contains a base64-encoded WAV file that can be directly used in HTML audio elements or saved to a file.

Speech-to-Text (Audio Input)

Speech-to-text is available via the /chat_generate endpoint using multipart/form-data: 
curl -X POST https://api.addisassistant.com/api/v1/chat_generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "chat_audio_input=@/path/to/your-audio.wav" \
  -F 'request_data={
    "target_language": "am"
  };type=application/json'
bash
:::important When using multipart/form-data, all JSON parameters must be wrapped inside a field named request_data. :::

Error Handling

The API returns standardized error responses with the following structure: 
{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "target": "optional target (e.g., language code)"
  }
}
json

Common Error Codes

| Code | HTTP Status | Description | | ---------------------- | ----------- | ----------------------------------- | | unauthorized | 401 | Missing authentication | | invalid_api_key | 401 | Invalid or expired API key | | invalid_input | 400 | Missing or invalid parameters | | unsupported_language | 400 | Requested language is not supported | | tts_failed | 500 | Text-to-speech conversion failed | | transcription_failed | 400 | Audio transcription failed | | invalid_json | 400 | Malformed JSON in request body | | method_not_allowed | 405 | HTTP method not supported | | internal_error | 500 | Unexpected server error |

Error Handling Best Practices

  1. Always check the status field to determine if the request was successful.
  2. For error responses, use the error.code for programmatic handling.
  3. Display the error.message to users as it contains human-readable explanations.
  4. Log the entire error response for debugging purposes.

Next Steps

PreviousNext