Documentation

Complete guide to integrating Balochi AI into your applications. Empower your community with advanced language AI.

Getting Started

Use Cases

Authentication

All API requests must be authenticated using an API Key. You can pass the key in theAuthorization header or the custom X-Balochi-Key header.

Header Format

Authorization: Bearer bk_7f8a9d...

Models

Balochi AI offers two optimized models. Use these branded names directly in your API requests.

Karsaz

FLASH

Fast, cost-effective model ideal for high-volume tasks, quick translations, and simple queries.

"model": "karsaz"

Zantkar

PRO

Our smartest model for complex reasoning, detailed research, and creative writing.

"model": "zantkar"

Chat API

The primary endpoint for interacting with our conversational models.
Note: This endpoint returns a Server-Sent Events (SSE) stream.

POSThttps://balochiai.com/api/chat

curl -N -X POST https://balochiai.com/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Start a conversation in Balochi about history",
    "model": "karsaz",
    "agentId": "OPTIONAL_AGENT_ID",
    "conversationHistory": [
      { "role": "user", "content": "Hello" },
      { "role": "assistant", "content": "Paher! Chone?" }
    ]
  }'

Response Format (SSE)

The API streams data chunks. Each chunk is a JSON object prefixed with data:.

data: {"text": "Hello, how can I help?"}
data: {"text": " I am..."}
data: [DONE]

Follow-up Questions

The model may suggest relevant follow-up questions at the end of a response. These are hidden in the stream with a specific delimiter:

...end of answer. ---FOLLOWUP---
What is the capital?
Tell me more history.
---END---

Parse the text between these markers to display interactive chips or buttons in your UI.

Agents API

Discover our "Ready Made" agents to plug directly into your apps.

GEThttps://balochiai.com/api/agents

Response Example

{
  "data": [
    {
      "id": "123e4567-e89b-...",
      "name": "Urdu Translator Person",
      "description": "Specialized in translating technical docs.",
      "type": "personality", // or "template"
      "model": "karsaz",
      "category": "general",
      "icon": "🤖"
    }
  ]
}

Call this endpoint to get the list of available agents. Copy the id from the response and use it as the agentId in your Chat API requests to speak with that specific persona!

Rate Limits

To ensure fair usage and stability, the API enforces two types of limits on your account:

Daily Requests

Hard limit on API calls per 24 hours

The total number of HTTP requests you can make in a single day. This resets at midnight UTC.

Error: 429 Too Many Requests

Monthly Tokens

Total AI token consumption per month

The aggregate number of input and output tokens processed across all your requests. Resets on the 1st of each month.

Error: 429 Monthly Limit Reached

Monitoring Usage

You can check your current usage and limits in real-time on your Developer Dashboard.

Custom Integrations

Learn how to integrate your own "BalochTech Assistant" or custom knowledge base into your external applications.

Option 1: Hosted Agent (Recommended)

Best for static knowledge bases like specific business services, FAQs, or brand personas.

Go to Personas in your dashboard and create a new Custom Persona (e.g., "BalochTech Assistant").

In the Instructions field, define your agent's role and knowledge:

"You are the official assistant for BalochTech. We offer web development, AI services, and..."

Copy the generated agentId and pass it in your API calls.

Why this is better

You can update your agent's knowledge in the Balochi AI dashboard instantly without changing a single line of code on your website!

Option 2: Dynamic Context Injection

Best for user-specific data (e.g., "Logged in as John, Premium Plan").

Inject specific context directly into the message or history array for each request.

// Payload Example { "model": "karsaz", "conversationHistory": [ { "role": "user", "content": "SYSTEM_INSTRUCTION: You are talking to user John (ID: 123). He is a premium subscriber." } ], "message": "What is my subscription status?" }

Function Calling

Empower parts of the model to look up real-time information from your database by defining "Tools".

Important: JSON Format

Use snake_case for keys: function_declarations (NOT functionDeclarations used in some Google SDKs).
Use UPPERCASE for types: "type": "OBJECT" (NOT "object").

1. Define Tools in Request

{ "model": "karsaz", "message": "Where is my order #555?", "tools": [{ "function_declarations": [{ "name": "check_order_status", "description": "Get current status of a customer order", "parameters": { "type": "OBJECT", "properties": { "orderId": { "type": "STRING", "description": "The ID of the order" } }, "required": ["orderId"] } }] }] }

2. Handle the "Call"

The API will return a function call object (data: {"functionCall": ...}) instead of text. You must execute this function in your backend code and return the result.

Real World Solutions

Humanitarian Aid Assistant

For NGOs and Non-Profits

Scenario: An aid organization needs to distribute critical health information to remote villages where Balochi is the primary language.

Implementation Strategy:

Create a "Health Guide" Agent via API.
Feed official WHO guidelines as context in the prompt.
Deploy a simple SMS or WhatsApp bot that hits our API.
Result: Villagers ask health questions in Balochi and receive accurate, medically-sound advice.

Virtual Balochi Tutor

For Schools and Universities

Scenario: A university wants to preserve the Balochi language and teach it to the next generation of students worldwide.

Implementation Strategy:

Integrate Balochi AI into the school's Learning Management System (LMS).
Use the API to grade grammar and suggest vocabulary improvements.
Create an interactive "Conversation Partner" for students to practice speaking without fear of judgment.

Civic Service Portal

For Government Agencies

Scenario: A local government wants to make public services accessible to all citizens, overcoming language barriers.

Implementation Strategy:

Build a "City Hall Assistant" widget for the government website.
Connect the API to a database of forms and procedures.
Citizens can ask "How do I renew my license?" in Balochi and get step-by-step guidance.
Security: Our core instruction enforcement ensures the bot remains professional and official at all times.