Quick Start

This guide will take you through the complete lifecycle: testing your ideas visually, securing an API key, and writing your first line of code.

Prototype in Playground

Before writing code, we recommend testing your prompts interactively.

Test your Parameters

Go to the Addis AI Playground.

Addis AI Playground Interface

Select a Model: Choose Addis-፩-አሌፍ for text or Addis-Audio for voice.
Adjust Temperature:
- Set to 0.2 for factual answers (History, Math).
- Set to 0.7 for creative writing (Stories, Poems).
Check Tokens: See how many tokens your Amharic query consumes.

Once you are happy with the result, you are ready to integrate.

Get your API Key

Authentication is handled via a secret x-api-key header.

Generate New Key

Navigate to the API Keys Dashboard.
Click Create API Key.

API Key Generation

Name your key (e.g., Addis AI App) in the popup window.

API Key Generation

Copy Secret

Important

You will see a key starting with sk_.... Copy this now.

You will not be able to see it again after closing the window.

API Key Generation

Configure Endpoints

All API requests should be made to the production Base URL:

https://api.addisassistant.com

Available Capabilities

Goal	Endpoint	Method
Chat / Text	`/api/v1/chat_generate`	`POST`
Text-to-Speech	`/api/v1/audio`	`POST`
Speech-to-Text	`/api/v2/stt`	`POST`

Quick Example

Choose a capability below to make your first request.

Endpoint: /api/v1/chat_generate

Simple JSON request for chatbots and text analysis.

cURL

curl -X POST https://api.addisassistant.com/api/v1/chat_generate \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_YOUR_KEY_HERE" \
  -d '{
    "model": "Addis-፩-አሌፍ",
    "prompt": "ሰላም፣ ኢትዮጵያ ውስጥ ስንት ክልሎች አሉ?",
    "target_language": "am",
    "temperature": 0.7
  }'

JavaScript

const response = await fetch("https://api.addisassistant.com/api/v1/chat_generate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "sk_YOUR_KEY_HERE",
  },
  body: JSON.stringify({
    model: "Addis-፩-አሌፍ",
    prompt: "ሰላም፣ ኢትዮጵያ ውስጥ ስንት ክልሎች አሉ?", 
    target_language: "am"
  }),
});

const data = await response.json();
console.log(data.response_text);

Endpoint: /api/v2/stt

Requires multipart/form-data. Note that metadata must be passed as a JSON string inside request_data.

cURL

curl --location 'https://api.addisassistant.com/api/v2/stt' \
  --header 'x-api-key: sk_YOUR_KEY_HERE' \
  --form 'audio=@"/path/to/your/audio.wav"' \
  --form 'request_data="{ \"language_code\": \"am\" }"'

JavaScript

const formData = new FormData();
formData.append("audio", fileInput.files[0]); // Your Audio File
formData.append("request_data", JSON.stringify({ language_code: "am" }));

const response = await fetch("https://api.addisassistant.com/api/v2/stt", {
  method: "POST",
  headers: {
    "x-api-key": "sk_YOUR_KEY_HERE"
  },
  body: formData
});

const data = await response.json();
console.log(data);

The Response

The API structure depends on the endpoint.

{
  "response_text": "በአሁኑ ጊዜ በኢትዮጵያ ውስጥ 12 ክልሎች አሉ።...",
  "finish_reason": "stop",
  "usage_metadata": {
    "prompt_token_count": 8,
    "candidates_token_count": 25,
    "total_token_count": 33
  },
  "modelVersion": "Addis-፩-አሌፍ"
}

{
    "status": "success",
    "data": {
        "transcription": "ሊያሳውቁ ይችላሉ ነገር ግን የበለጠ እየታወቁ በመጡ ቁጥር ደግሞ ይበልጥ ይነሳሉ የተረጋገጠ ልብና ነበር ያለው ሰው የሃሳብ የድርጊት ዝም",
        "usage_metadata": {
            "totalBilledDuration": "15s",
            "requestId": "69b60667-0000-2a1e-b6d3-d4f547fe6724"
        }
    },
    "confidence": 0.98276204
}

Quick Start

On this page