Text Generation (Chat)

The text generation capability allows you to create natural language responses in Amharic and Afan Oromo using the /chat_generate endpoint. This core API enables intelligent conversations and text generation in Ethiopian languages.

Overview and Use Cases

The text generation API is powered by our Addis-፩-አሌፍ model, which has been trained on a diverse corpus of Ethiopian language content. This capability enables:

Conversational AI: Create chatbots and virtual assistants that communicate naturally in Amharic and Afan Oromo
Content Creation: Generate articles, stories, educational materials, or marketing content
Question Answering: Build knowledge-based systems that respond to user queries in local languages
Language Processing: Perform summarization, classification, and entity extraction
Custom Applications: Develop specialized tools for legal, medical, educational, or customer service domains

Request Format

Basic JSON Request

Endpoint: POST /chat_generate

{
  "prompt": "የኢትዮጵያ የታሪክ ቦታዎችን አስረዳኝ",
  "target_language": "am",
  "generation_config": {
    "temperature": 0.7,
    "maxOutputTokens": 1200
  }
}

json

Full Request Parameters

{
  "prompt": "What is the capital of Ethiopia?",
  "target_language": "am" | "om",
  "conversation_history": [
    {"role": "user", "content": "previous message"},
    {"role": "assistant", "content": "previous response"}
  ],
  "generation_config": {
    "temperature": 0.7,
    "stream": false,
    "maxOutputTokens": 1200
  },
  "attachment_field_names": ["image1", "document1"] // for multipart/form-data
}

json

Required Parameters

| Parameter | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------- | | prompt | string | The text input/question for the model to respond to | | target_language | string | Language code for the response: am (Amharic) or om (Afan Oromo) |

Optional Parameters

| Parameter | Type | Description | | ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------- | | conversation_history | array | Previous exchanges to maintain context (see Conversation Management) | | generation_config | object | Settings to control the generation behavior | | attachment_field_names | array | Names of attachment fields when using multipart/form-data (see Multi-modal Input) |

Response Format

{
  "response_text": "የኢትዮጵያ ዋና ከተማ አዲስ አበባ ናት።",
  "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 Fields

| Field | Type | Description | | ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ | | response_text | string | The generated text response | | finish_reason | string | Reason the generation completed: stop (natural end), length (reached token limit), content_filter (filtered), etc. | | usage_metadata | object | Token count information for billing and monitoring | | modelVersion | string | The model version used for generation | | uploaded_attachments | array | Information about uploaded files (only when attachments are used) | | transcription_raw | string | Raw transcription with analysis (only when audio input is provided) | | transcription_clean | string | Clean transcription text (only when audio input is provided) |

Streaming vs. Non-streaming

Non-streaming (Default)

The default mode returns a complete response when generation is finished:

Pros: Simple to implement, guaranteed complete response
Cons: Higher perceived latency for longer responses
Best for: Short responses, simple implementations, back-end processing

Streaming

Streaming mode sends response chunks as they're generated:

Pros: Better user experience with immediate feedback
Cons: More complex to implement on the client side
Usage: Set "stream": true in the generation_config object

:::caution Chat streaming is currently in BETA and not recommended for production environments. For production applications, please use the default non-streaming mode. :::

Language Selection

The target_language parameter determines the output language:

"am" - Amharic (uses Ge'ez script)
"om" - Afan Oromo (uses Latin script)

The model will generate responses in the specified language regardless of the input language. This allows for cross-language interactions where users can input in one language and receive responses in another.

Configuration Options

The generation_config object allows fine-tuning of the text generation: | Parameter | Type | Default | Range | Description | | ----------------- | ------- | ------- | ------- | ------------------------------------------------------------------------------------- | | temperature | float | 0.7 | 0.0-1.0 | Controls randomness: lower values are more deterministic, higher values more creative | | maxOutputTokens | integer | 1200 | 10-8192 | Maximum length of the generated response | | stream | boolean | false | - | Enable/disable streaming response mode |

Temperature Settings Guide

0.0-0.3: Very deterministic, good for factual Q&A and specific instructions
0.4-0.6: Balanced, suitable for most applications
0.7-0.8: More varied output, good for creative content
0.9-1.0: Maximum creativity and variability

Code Examples

Basic Request (JavaScript)

async function generateText() {
  const response = await fetch(
    "https://api.addisassistant.com/api/v1/chat_generate",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": "YOUR_API_KEY",
      },
      body: JSON.stringify({
        prompt: "ኢትዮጵያ ውስጥ ያሉ የታሪክ ቦታዎችን ንገረኝ",
        target_language: "am",
        generation_config: {
          temperature: 0.7,
        },
      }),
    },
  );

  const result = await response.json();
  return result.response_text;
}

javascript

Streaming Example (JavaScript)

async function streamingGenerate() {
  const response = await fetch(
    "https://api.addisassistant.com/api/v1/chat_generate",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": "YOUR_API_KEY",
      },
      body: JSON.stringify({
        prompt: "ኢትዮጵያ ውስጥ ያሉ የታሪክ ቦታዎችን ንገረኝ",
        target_language: "am",
        generation_config: {
          temperature: 0.7,
          stream: true,
        },
      }),
    },
  );

  // Process the streaming response
  const reader = response.body.getReader();
  let decoder = new TextDecoder();
  let result = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split("\n").filter((line) => line.trim());

    for (const line of lines) {
      try {
        const data = JSON.parse(line);
        result += data.response_text || "";

        // Update UI with partial text
        document.getElementById("response").textContent = result;
      } catch (e) {
        console.error("Error parsing chunk:", e);
      }
    }
  }

  return result;
}

javascript

Best Practices

Use Appropriate Temperature Settings
- For factual responses, use lower temperatures (0.1-0.3)
- For creative content, use higher temperatures (0.7-0.9)
Provide Clear Instructions
- Be specific in your prompts to get better responses
- Include formatting requirements in the prompt itself
Manage Token Usage
- Set reasonable maxOutputTokens to control response length
- Use shorter prompts when possible to reduce costs
Handle Errors Gracefully
- Always check for the status field to detect errors
- Implement retry logic for transient failures
Respect Content Guidelines
- The model has content filtering for harmful or inappropriate content
- Design your application to handle cases where content is filtered
Language Considerations
- Use proper Amharic or Afan Oromo orthography in prompts when possible
- The model can handle romanized input but performs best with native script

For more advanced usage patterns, explore the sections on Multi-modal Input and Conversation Management.

Previous Next