Addis AI Logo

Request/Response Schemas

This page details the JSON schemas for all Addis AI API endpoints, including request formats, response structures, and data types.

Overview

Addis AI API follows RESTful conventions with JSON-based request and response bodies. Understanding these schemas will help you properly format your requests and parse the responses.

Common Data Types

Message Object

Messages represent conversation turns in the chat API. 
{
  "role": string,     // "system", "user", or "assistant"
  "content": string,  // The content of the message
  "name": string      // Optional identifier for the message author
}
json

Completion Choice Object

Represents a completion choice returned by the model. 
{
  "message": {
    "role": string,
    "content": string
  },
  "finish_reason": string,  // "stop", "length", "content_filter", "function_call"
  "index": number           // Index of this completion choice
}
json

Usage Information Object

Contains token usage information for a request. 
{
  "prompt_tokens": number,      // Tokens used in the prompt
  "completion_tokens": number,  // Tokens used in the completion
  "total_tokens": number        // Total tokens used
}
json

Chat Completion

Request

POST /v1/chat/completions
{
  "model": string,               // Model to use (e.g., "addis-1-alef")
  "messages": Array<Message>,    // Array of message objects
  "temperature": number,         // Optional: Controls randomness (0.0-2.0)
  "top_p": number,               // Optional: Nucleus sampling parameter (0.0-1.0)
  "n": number,                   // Optional: Number of completions to generate
  "stream": boolean,             // Optional: Stream responses as they're generated
  "max_tokens": number,          // Optional: Maximum number of tokens to generate
  "language": string,            // Optional: "am" for Amharic, "om" for Afan Oromo
  "presence_penalty": number,    // Optional: Penalty for repetitive tokens (0.0-2.0)
  "frequency_penalty": number    // Optional: Penalty for frequently occurring tokens (0.0-2.0)
}
json

Response

{
  "id": string,                    // Unique identifier for the completion
  "object": "chat.completion",     // Object type
  "created": number,               // Unix timestamp of creation time
  "model": string,                 // Model used for completion
  "choices": Array<Choice>,        // Array of completion choices
  "usage": {                       // Token usage information
    "prompt_tokens": number,
    "completion_tokens": number,
    "total_tokens": number
  }
}
json

Streaming Response

When stream is set to true, the response is a stream of server-sent events, each containing a chunk of the response in the following format: 
{
  "id": string,
  "object": "chat.completion.chunk",
  "created": number,
  "model": string,
  "choices": [
    {
      "delta": {
        "role": string,         // Only in the first chunk
        "content": string       // Content delta
      },
      "index": number,
      "finish_reason": null     // null until the final chunk
    }
  ]
}
json
The final chunk will have a finish_reason other than null.

Text-to-Speech

Request

POST /v1/audio/speech
{
  "text": string,             // Text to convert to speech
  "language": string,         // "am" for Amharic, "om" for Afan Oromo
  "voice_id": string,         // Voice ID (e.g., "female-1", "male-1")
  "output_format": string,    // Optional: "mp3", "wav", "ogg" (default: "mp3")
  "speed": number,            // Optional: Speech speed (0.5-1.5, default: 1.0)
  "pitch": number             // Optional: Voice pitch adjustment (-1.0 to 1.0)
}
json

Response

The response is a binary audio file in the requested format with appropriate content type headers.

Speech-to-Text

Request

Multipart form data: 
POST /v1/audio/transcribe
Content-Type: multipart/form-data


audio: file              // Audio file to transcribe
language: string         // Optional: "am" for Amharic, "om" for Afan Oromo
                         // If not specified, language will be auto-detected
prompt: string           // Optional: Text to guide the transcription
timestamp_granularities: // Optional: "word" or "segment" for timestamps
text

Response

{
  "id": string,                    // Unique identifier for this transcription
  "text": string,                  // Transcribed text
  "language": string,              // Detected or specified language
  "duration": number,              // Duration of the audio in seconds
  "timestamps": Array<Timestamp>,  // Optional: Word or segment timestamps if requested
  "segments": Array<Segment>       // Optional: Detailed segments if timestamps requested
}
json
Where Timestamp and Segment are defined as: 
// Timestamp object (if timestamps were requested)
{
  "text": string,         // Word or segment text
  "start": number,        // Start time in seconds
  "end": number           // End time in seconds
}


// Segment object (if timestamps were requested)
{
  "id": number,           // Segment ID
  "text": string,         // Segment text
  "start": number,        // Start time in seconds
  "end": number,          // End time in seconds
  "confidence": number    // Confidence score (0.0-1.0)
}
json

Multi-Modal Input

Request

Multipart form data: 
POST /v1/chat/multimodal
Content-Type: multipart/form-data


messages: JSON string    // Same as chat completions messages
language: string         // "am" for Amharic, "om" for Afan Oromo
images: file(s)          // One or more image files
audio: file              // Optional: Audio file
options: JSON string     // Optional: Additional parameters
text
Where options can contain: 
{
  "temperature": number,
  "top_p": number,
  "max_tokens": number,
  "stream": boolean
}
json

Response

The response format is the same as the chat completions API.

Error Responses

All API endpoints follow a consistent error response format: 
{
  "error": {
    "message": string,      // Human-readable error message
    "type": string,         // Error type identifier
    "param": string,        // Optional: Parameter that caused the error
    "code": string          // Optional: Error code
  }
}
json
For more details on error codes and handling, see the Error Handling guide.

Rate Limit Response Headers

All API responses include headers with rate limit information: 
x-ratelimit-limit: 60         // Requests allowed per time window
x-ratelimit-remaining: 59     // Requests remaining in current window
x-ratelimit-reset: 1677803439 // Unix timestamp when the limit resets
text
For more details on rate limits, see the Rate Limits page.

Conclusion

This reference covers the primary schemas for Addis AI API endpoints. For additional details about specific endpoint behavior, refer to the API Endpoints documentation. If you encounter any issues or have questions about these schemas, please refer to our FAQ and Troubleshooting guide.
PreviousNext