API Documentation

Get your first AI response in 3 steps.

import Tchavi from '@tchavi/sdk';

const client = new Tchavi({ apiKey: 'YOUR_API_KEY' });

const response = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello!' }],
});

console.log(response.choices[0].message.content);
console.log('Credits used:', response.tchavi.credits_used);

All API requests require a valid API key sent in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys can be created and managed from your dashboard. Each key is tied to your account's credit balance. You can create multiple keys for different projects.

Keep your API keys secret. Do not share them in client-side code, public repositories, or URLs.

# .env
TCHAVI_API_KEY="sk-tch_..."

# Node.js
const client = new Tchavi({ apiKey: process.env.TCHAVI_API_KEY });

# Python
import os
client = OpenAI(api_key=os.environ["TCHAVI_API_KEY"], base_url="...")

https://tchavi.com/api/api/v1

Tchavi is 100% compatible with the OpenAI API format. If you already use the OpenAI SDK or any OpenAI-compatible library, just change the base URL and API key — the rest of your code stays the same.

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://tchavi.com/api/api/v1',
});

const response = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello!' }],
});

console.log(response.choices[0].message.content);

Generate a chat completion from a list of messages. This is the primary endpoint for text generation with all supported models.

Request body

Example request

import Tchavi from '@tchavi/sdk';

const client = new Tchavi({ apiKey: 'YOUR_API_KEY' });

const response = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is the capital of Benin?' },
  ],
  temperature: 0.7,
});

console.log(response.choices[0].message.content);
console.log('Credits used:', response.tchavi.credits_used);

Example response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1711234567,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of Benin is Porto-Novo."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 12,
    "total_tokens": 36
  },
  "tchavi": {
    "credits_used": 2,
    "credits_remaining": 498,
    "model_tier": "budget"
  }
}

Streaming

Set stream: true to receive the response token-by-token as Server-Sent Events (SSE). This lets you display text as it arrives rather than waiting for the full response.

import Tchavi from '@tchavi/sdk';

const client = new Tchavi({ apiKey: process.env.TCHAVI_API_KEY });

const stream = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Tell me a short story.' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

Generate images from text prompts across all supported image models — Nano Banana, Imagen, GPT Image, DALL·E, and more. The same endpoint also handles image editing when you pass reference images (aliased as POST /v1/images/edits).

Common request body

The fields below are shared by every image model. Model-specific options — size, aspect_ratio, resolution, quality, output_format, negative_prompt, seed, background, etc. — depend on the family. Open the model on /models and switch to the API tab for the full parameter reference.

Example

Swap model for any image model ID — parameters beyond those shown below must match that model's API tab.

import Tchavi from '@tchavi/sdk';

const client = new Tchavi({ apiKey: 'YOUR_API_KEY' });

const result = await client.images.generations.create({
  model: 'YOUR_MODEL_ID',
  prompt: 'A colorful parrot on a branch, digital art',
});

console.log(result.data[0].b64_json);
console.log('Credits used:', result.tchavi.credits_used);

The response contains base64-encoded image data in data[0].b64_json. Here's how to use it:

// Display the image in a browser
const img = document.createElement('img');
img.src = `data:image/png;base64,${data.data[0].b64_json}`;
document.body.appendChild(img);

Tchavi supports two audio endpoints: text-to-speech (TTS) for generating audio from text, and transcription (Whisper) for converting audio files to text.

Text-to-Speech

Converts text to spoken audio. Returns raw audio bytes.

import Tchavi from '@tchavi/sdk';
import { writeFileSync } from 'fs';

const client = new Tchavi({ apiKey: 'YOUR_API_KEY' });

const response = await client.audio.speech.create({
  model: 'tts-1',
  input: 'Tchavi is the best AI API gateway in Africa.',
  voice: 'nova',
  response_format: 'mp3',
});

const buffer = Buffer.from(await response.arrayBuffer());
writeFileSync('speech.mp3', buffer);

Transcription (Whisper)

Transcribes audio files to text. Send as multipart/form-data.

import Tchavi from '@tchavi/sdk';
import { createReadStream } from 'fs';

const client = new Tchavi({ apiKey: 'YOUR_API_KEY' });

const result = await client.audio.transcriptions.create({
  model: 'whisper-1',
  file: createReadStream('audio.mp3'),
  language: 'fr',
});

console.log(result.text);
console.log('Duration:', result.tchavi.duration_minutes, 'min');
console.log('Credits used:', result.tchavi.credits_used);

Embeddings convert text into a numeric vector that captures its semantic meaning. Use them for semantic search (find content by meaning, not keywords), clustering similar documents, recommendations, and RAG (retrieval-augmented generation) pipelines.

import Tchavi from '@tchavi/sdk';

const client = new Tchavi({ apiKey: 'YOUR_API_KEY' });

const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'Tchavi is the best AI API gateway in Africa.',
});

console.log(response.data[0].embedding);

Video generation runs asynchronously: the endpoint returns a 202 with a job.id immediately, and the video renders in the background. Poll GET /v1/jobs/:id (see Async Jobs) until status becomes completed or failed. The SDK's createAndWait(...) helper does both in one call.

Billing is per second of output, resolution-dependent: 480p = 260 cr/sec · 720p = 580 cr/sec. A typical 10-second 480p clip costs 2,600 credits. If a job fails after billing (upstream error, timeout), the charged credits are automatically refunded.

import Tchavi from '@tchavi/sdk';

const client = new Tchavi({ apiKey: 'YOUR_API_KEY' });

// One-liner: submit + poll until completed/failed
const job = await client.videos.generations.createAndWait({
  model: 'seedance-2',
  prompt: 'A cinematic shot of the Cotonou Amazone statue at golden hour',
  duration: 5,
  resolution: '480p',
  aspect_ratio: '9:16',
  generate_audio: true,
});

if (job.status === 'completed') {
  console.log('Video URL:', job.output?.video_url);
  console.log('Credits used:', job.tchavi?.credits_used);
} else {
  console.error('Failed:', job.error?.message);
}

Some endpoints — currently video generation — run asynchronously. They respond immediately with a job id and you track completion via these endpoints.

Retrieve a job

Returns the full job record. The payload shape depends on status:

• pending / processing — no output yet; tchavi.credits_used is set.
• completed — output.video_url, output.duration, output.resolution, output.file_size_mb, output.url_expires_at.
• failed — error.message, error.code, and tchavi.credits_refunded (the charged credits are returned automatically).

List jobs

Lists the caller's jobs, most recent first. Query params: status (filter), limit (1–50, default 20), offset (default 0).

import Tchavi from '@tchavi/sdk';
const client = new Tchavi({ apiKey: 'YOUR_API_KEY' });

// Retrieve a specific job
const job = await client.jobs.retrieve('job_abc123');
console.log(job.status, job.output?.video_url);

// List the 10 most recent completed jobs
const { data } = await client.jobs.list({ status: 'completed', limit: 10 });
for (const j of data) {
  console.log(j.created_at, j.model, j.output?.video_url);
}

Tchavi gives you access to 40+ AI models from OpenAI, Anthropic, Google, and more — all through a single API. Models are organized into budget groups:

See all available models on the Models page. New models are added within 48 hours of release.

Tchavi uses a credit-based billing system. Each API request consumes credits based on the model used and the number of tokens processed.

How credits are calculated

• Chat models: Credits = (input_tokens × rate + output_tokens × rate) per 1K tokens
• Image models: Flat credit cost per image based on resolution
• TTS (text-to-speech): Credits per 1K characters of input text
• Transcription (Whisper): Credits per minute of audio

Response headers

Every API response includes metadata headers:

Recharging

Buy credit packs from your billing dashboard using Wave, Orange Money, MTN MoMo, and 30+ mobile money operators. Credits are added instantly after payment.

Tchavi is pay-as-you-go: every user can call every model, and credits are the natural gate. Rate limits depend on your account level, which is unlocked automatically based on your lifetime spend on the platform — there is no subscription. Two independent limits apply per user per minute:

• RPM — maximum number of requests per minute.
• TPM — maximum tokens processed per minute (input + output). For TTS, each character counts as 1 token. For Whisper, each billed minute counts as 1,000 tokens.

A global IP-based limit of 500 req/min also applies across all users sharing the same IP address.

When a limit is exceeded you receive a 429 response with a Retry-After header indicating how many seconds to wait before retrying. Your current level, RPM budget, and TPM budget are always visible in the X-RateLimit-* response headers (see Credits & Billing).

Tchavi returns standard HTTP status codes. Errors include a JSON body:

{
  "error": {
    "code": "insufficient_credits",
    "message": "You don't have enough credits for this request.",
    "status": 402
  }
}

Common error codes

@tchavi/sdk (recommended)

Our official SDK wraps the API with type-safe methods and credit tracking.

npm install @tchavi/sdk

import Tchavi from '@tchavi/sdk';

const client = new Tchavi({ apiKey: 'YOUR_API_KEY' });

// Chat
const chat = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello!' }],
});

// Images
const images = await client.images.generations.create({
  model: 'nano-banana-pro',
  prompt: 'A futuristic Cotonou skyline at dusk',
});

// Audio — TTS
const tts = await client.audio.speech.create({
  model: 'tts-1',
  input: 'Welcome to Tchavi',
  voice: 'nova',
});

// Video — async; createAndWait polls until completed/failed
const video = await client.videos.generations.createAndWait({
  model: 'seedance-2',
  prompt: 'A cinematic shot at golden hour',
  duration: 5,
  resolution: '480p',
});

// Retrieve / list async jobs
const job = await client.jobs.retrieve(video.id);
const { data } = await client.jobs.list({ status: 'completed', limit: 10 });

OpenAI SDK (drop-in)

Already using the OpenAI Python or Node.js SDK? Just change the base URL:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://tchavi.com/api/api/v1",
)

# Use it exactly like OpenAI
response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://tchavi.com/api/api/v1',
});

const response = await client.chat.completions.create({
  model: 'claude-sonnet-4-6',
  messages: [{ role: 'user', content: 'Hello!' }],
});

console.log(response.choices[0].message.content);

cURL

No SDK needed — use standard HTTP requests:

curl -X POST https://tchavi.com/api/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'