Operation manual

Overview

Afri Nexus AI gives you one API key and one prepaid balance for text, image and video models from OpenAI, Anthropic, Google, DeepSeek, Zhipu AI, Moonshot, MiniMax, Alibaba, xAI, ByteDance and Kuaishou. The API follows the OpenAI format, so the official OpenAI SDKs and any tool that accepts a custom base URL work unchanged. Claude models additionally accept Anthropic’s native Messages API.

This manual covers the whole journey: creating a key, calling chat, image and video models, the specifics of each provider’s models (with links to the provider’s own manual), billing, and troubleshooting. https://afri-nexus.io/v1 is accepted as a base URL too; https://api.afri-nexus.io/v1 is the recommended one.

Quick start

1. Create an account. Sign up with your e-mail address, then sign in to the console.
2. Add credit. Open Wallet → Top-up. Your balance is shown in US dollars; redeem codes are entered on the same page.
3. Create an API key. Go to API Keys → Create API Key. Give it a name and, most importantly, choose its group: the group decides which model family the key can call (see Key groups). You can also set a spending limit, an expiry date and IP or model restrictions. Copy the key (it starts with sk-) and keep it secret.
4. Pick a model. The Model Square lists every live model with its price; use the model ID exactly as written.
5. Send a request. The example below calls Claude Sonnet 5.5 with a key from the claude-special group.

curl https://api.afri-nexus.io/v1/chat/completions \
  -H "Authorization: Bearer $AFRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "messages": [
      {"role": "user", "content": "Explain how a mobile money payment API works, in three short sentences."}
    ]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://api.afri-nexus.io/v1",
    api_key="sk-...",
)

response = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[{"role": "user", "content": "Explain how a mobile money payment API works, in three short sentences."}],
)
print(response.choices[0].message.content)
print(response.usage)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.afri-nexus.io/v1",
  apiKey: process.env.AFRI_API_KEY,
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-5-5",
  messages: [{ role: "user", content: "Explain how a mobile money payment API works, in three short sentences." }],
});
console.log(response.choices[0].message.content);
console.log(response.usage);

Key groups and models

Each group corresponds to one provider line and one discount level, already built into the prices shown in the Model Square. When you create a key you pick its group in the Group field; the API Keys table shows the group of every existing key, and GET /v1/models with that key returns exactly the models it can call.

The complete list of model IDs, with the endpoint each one uses:

curl https://api.afri-nexus.io/v1/models -H "Authorization: Bearer $AFRI_API_KEY"

Authentication and base URL

Send your key in the Authorization header of every request. Anthropic’s native endpoint also accepts the x-api-key header used by the Anthropic SDKs.

• Keep keys on your server or in a secrets manager; never ship them in a mobile app or a public web page. Create one key per project or environment so you can revoke one without affecting the others.
• Use the per-key spending limit, expiry date and IP allow-list in the console to limit the damage if a key leaks.
• A deleted or disabled key is rejected immediately with HTTP 401.

Chat completions (text models)

POST https://api.afri-nexus.io/v1/chat/completions serves every text model: GPT-6, Claude, Gemini, DeepSeek, GLM, Kimi, MiniMax, Qwen and Grok. The request and response are the standard OpenAI Chat Completions objects.

Request fields

Response

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "claude-sonnet-5-5",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 27,
    "completion_tokens": 74,
    "total_tokens": 101,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 0}
  }
}

usage is what you are billed for: prompt_tokens (input, with cached_tokens billed at the cache-read rate), completion_tokens (output, which includes any reasoning_tokens).

Streaming

curl https://api.afri-nexus.io/v1/chat/completions \
  -H "Authorization: Bearer $AFRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "stream": true,
    "stream_options": {"include_usage": true},
    "messages": [{"role": "user", "content": "Explain how a mobile money payment API works, in three short sentences."}]
  }'

stream = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Explain how a mobile money payment API works, in three short sentences."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage)

const stream = await client.chat.completions.create({
  model: "deepseek-v4.1-flash",
  messages: [{ role: "user", content: "Explain how a mobile money payment API works, in three short sentences." }],
  stream: true,
  stream_options: { include_usage: true },
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
  if (chunk.usage) console.log("\n", chunk.usage);
}

Each chunk arrives as a data: line containing a chat.completion.chunk object; the stream ends with data: [DONE]. Use streaming for long answers: it shows progress to your users and avoids the 100-second request limit described in Errors and limits.

Images in the prompt (vision)

Multimodal models (for example GPT-6, Claude, Gemini, Kimi K3.1 Pro, Qwen 3.8) accept image parts next to the text. Pass a public HTTPS URL or a data:image/jpeg;base64,… URI.

{
  "model": "gemini-3.8-flash",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What is written on this receipt? Return the total."},
        {"type": "image_url", "image_url": {"url": "https://example.com/receipt.jpg"}}
      ]
    }
  ]
}

Tools (function calling)

{
  "model": "gpt-6-astra",
  "messages": [{"role": "user", "content": "What is the weather in Antananarivo?"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

When the model decides to call a tool, the response contains tool_calls with the function name and JSON arguments; run the function, then send the result back as a tool message and call the API again.

JSON answers

{
  "model": "qwen3.8-max",
  "response_format": {"type": "json_object"},
  "messages": [
    {"role": "system", "content": "Answer with a JSON object: {\"city\": string, \"country\": string}."},
    {"role": "user", "content": "Where is the Avenue of the Baobabs?"}
  ]
}

Reasoning models

Several models think before they answer. Reasoning tokens are billed as output tokens and appear in usage.completion_tokens_details.reasoning_tokens. Each provider controls thinking with its own parameter, which the gateway forwards unchanged:

# Qwen: turn thinking off for a short, cheap answer
client.chat.completions.create(
    model="qwen3.8-flash",
    messages=[{"role": "user", "content": "2 + 2 ?"}],
    extra_body={"enable_thinking": False},
)

# Kimi K3.1 Pro: choose the reasoning depth
client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "user", "content": "..."}],
    reasoning_effort="low",
)

# DeepSeek: read the reasoning separately from the answer
r = client.chat.completions.create(
    model="deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "..."}],
)
print(r.choices[0].message.reasoning_content)
print(r.choices[0].message.content)

Claude: native Messages API

All claude-* models also accept Anthropic’s own format at POST https://api.afri-nexus.io/v1/messages. Use it when you need Claude-specific features: extended thinking, prompt caching, tool use with Anthropic’s schema, or an existing Anthropic SDK integration (just change base_url and the key).

curl https://api.afri-nexus.io/v1/messages \
  -H "x-api-key: $AFRI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 4096,
    "thinking": {"type": "adaptive"},
    "messages": [{"role": "user", "content": "Explain how a mobile money payment API works, in three short sentences."}]
  }'

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.afri-nexus.io",
    api_key="sk-...",
)

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    thinking={"type": "adaptive"},
    messages=[{"role": "user", "content": "Explain how a mobile money payment API works, in three short sentences."}],
)
print(next(b.text for b in message.content if b.type == "text"))
print(message.usage)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.afri-nexus.io",
  apiKey: process.env.AFRI_API_KEY,
});

const message = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 4096,
  thinking: { type: "adaptive" },
  messages: [{ role: "user", content: "Explain how a mobile money payment API works, in three short sentences." }],
});
console.log(message.content.find((b) => b.type === "text")?.text);
console.log(message.usage);

• Thinking. On the current generation (Opus 5.5, Sonnet 5.5, Fable 5.1, Haiku 5.5) thinking is adaptive by default; send "thinking": {"type": "adaptive"} explicitly if you like. The older budget_tokens form is rejected by these models. The depth of reasoning is controlled with output_config.effort as described in Anthropic’s extended-thinking guide.
• Prompt caching. Mark the stable prefix (system prompt, reference documents, tool definitions) with cache_control; repeated requests are billed at the cache-read rate shown in the Model Square. Cache writes are billed at the cache-write rate.
• Streaming. "stream": true returns the standard Anthropic event stream (message_start, content_block_delta, …).
• Two lines, one format. claude-opus-5-5 (group claude-special) and claude-opus-5-5-official (group claude-official) are the same model behind two routes and two prices; pick the line that matches your key.

{
  "model": "claude-sonnet-5-5-official",
  "max_tokens": 2048,
  "system": [
    {
      "type": "text",
      "text": "<your long, stable instructions or reference document>",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "Summarize the key points."}]
}

Claude Code and Anthropic SDK tools

Any tool built on the Anthropic SDK can point at Afri Nexus through the standard environment variables:

export ANTHROPIC_BASE_URL="https://api.afri-nexus.io"
export ANTHROPIC_API_KEY="sk-..."
export ANTHROPIC_MODEL="claude-opus-5-5"
claude

Image generation

POST https://api.afri-nexus.io/v1/images/generations follows the OpenAI Images API. Two families are available: GPT Image (gpt-image-2, gpt-image-2.5-flare and their -2k / -4k variants, key group image-gpt-image) and Nano Banana (nano-banana-2, nano-banana-pro, Google’s Gemini image models, key group image-nano-banana).

curl https://api.afri-nexus.io/v1/images/generations \
  -H "Authorization: Bearer $AFRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A market stall in Antananarivo at sunrise, warm light, photo style",
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

import base64

result = client.images.generate(
    model="gpt-image-2",
    prompt="A market stall in Antananarivo at sunrise, warm light, photo style",
    size="1024x1024",
    output_format="png",
    response_format="b64_json",
)
with open("image.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

import fs from "node:fs";

const result = await client.images.generate({
  model: "gpt-image-2",
  prompt: "A market stall in Antananarivo at sunrise, warm light, photo style",
  size: "1024x1024",
  output_format: "png",
  response_format: "b64_json",
});
fs.writeFileSync("image.png", Buffer.from(result.data[0].b64_json, "base64"));

{
  "created": 1760200000,
  "data": [
    {"b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."}
  ]
}

Parameters

Resolution tiers

Images are billed per image at the tier’s price (Model Square → model → Details). The -2k and -4k model names are priced at their tier regardless of the size you send, so pair them with a matching 2K or 4K size. A 1K image usually takes 15–60 seconds; 4K images can take longer, so keep interactive use at 1K and generate large sizes in the background.

Editing an image

POST https://api.afri-nexus.io/v1/images/edits (multipart form: image, prompt, model, optional mask) follows the OpenAI format for the GPT Image and Nano Banana models.

Video generation

Video is asynchronous: you submit a task, poll its status, then download the clip. Video models are split by provider into three key groups: seedance-official (Seedance 2.0, 2.5, 2.0 Fast and 2.0 Mini), wan (Wan 3.0) and kling (Kling 3.0); a key calls only the models of its own group.

1. Submit

curl https://api.afri-nexus.io/v1/videos \
  -H "Authorization: Bearer $AFRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "A fishing boat leaves a Malagasy harbour at dawn, cinematic, slow push-in",
    "seconds": 5,
    "resolution": "480p"
  }'

{
  "id": "task_01HZ...",
  "object": "video",
  "model": "seedance-2.0-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1760200000
}

2. Poll, then download

curl https://api.afri-nexus.io/v1/videos/TASK_ID \
  -H "Authorization: Bearer $AFRI_API_KEY"

# -> {"id": "TASK_ID", "object": "video", "status": "in_progress", "progress": 40, ...}
# -> {"id": "TASK_ID", "object": "video", "status": "completed", "progress": 100, ...}

curl -L https://api.afri-nexus.io/v1/videos/TASK_ID/content \
  -H "Authorization: Bearer $AFRI_API_KEY" -o video.mp4

Status goes queued → in_progress → completed (or failed, with an error object). Poll every 10–15 seconds; a clip typically takes 1–5 minutes depending on model, duration and resolution.

Request fields

Models

When you submit, the estimated cost is reserved on your balance; when the task completes it is settled on the provider’s reported usage, and a failed task releases the reservation. Live per-second and per-token rates are in the Model Square; the Usage logs show one line at submission and one at settlement.

Image-to-video in Python

import time, requests

API = "https://api.afri-nexus.io/v1"
H = {"Authorization": "Bearer sk-..."}

task = requests.post(f"{API}/videos", headers=H, json={
    "model": "wan3.0-video",
    "prompt": "A fishing boat leaves a Malagasy harbour at dawn, cinematic, slow push-in",
    "images": ["https://example.com/first-frame.jpg"],
    "seconds": 5,
    "resolution": "720P",
}).json()

while True:
    status = requests.get(f"{API}/videos/{task['id']}", headers=H).json()
    if status["status"] in ("completed", "failed"):
        break
    time.sleep(10)

if status["status"] == "completed":
    mp4 = requests.get(f"{API}/videos/{task['id']}/content", headers=H)
    open("video.mp4", "wb").write(mp4.content)
else:
    print(status.get("error"))

Kling with native audio

{
  "model": "kling-V3",
  "prompt": "...",
  "seconds": 5,
  "resolution": "1080p",
  "ratio": "16:9",
  "generate_audio": true
}

Model reference by provider

Afri Nexus relays each request to the model’s provider, so the provider’s own manual is the reference for prompt formats, parameters, context windows and behaviour. The cards below list what we serve from each provider, what to keep in mind on our gateway, and the official documentation to read. Prices: the Model Square cards show the provider’s official list price; open a model’s Details to see the Afri Nexus price and the discount.

SDKs, coding assistants and no-code tools

Official SDKs

• OpenAI SDKs (Python, Node.js, Go, Java, .NET, PHP…): set the base URL to https://api.afri-nexus.io/v1 and the API key to your Afri key. Everything in Chat completions and Image generation works through them.
• Anthropic SDKs (Python, TypeScript, Java, Go…): set base_url to https://api.afri-nexus.io; see Claude: native Messages API.
• LangChain, LlamaIndex, Vercel AI SDK and similar frameworks: use their OpenAI-compatible provider with the same base URL and key.

Coding assistants

Any editor or agent that accepts a custom OpenAI-compatible base URL runs on your Afri balance: Cursor, Cline, Roo Code, Continue, Zed, opencode, aider, Kilo Code… In the tool’s provider settings choose “OpenAI compatible”, enter https://api.afri-nexus.io/v1, your key, and a model ID from your key’s group (for example claude-sonnet-5-5, gpt-6-astra, kimi-k3.1-pro). Tools built on the Anthropic SDK, such as Claude Code, use the environment variables shown in the Claude section.

No-code automation (n8n, Make, Zapier)

Use an HTTP request node with the JSON body below, or the tool’s OpenAI node with a custom base URL. Plain JSON in, plain JSON out:

POST https://api.afri-nexus.io/v1/chat/completions
Authorization: Bearer sk-...
Content-Type: application/json

{
  "model": "gemini-3.8-flash",
  "messages": [
    {"role": "system", "content": "Reply in the customer's language."},
    {"role": "user", "content": "{{ $json.message }}"}
  ]
}

Desktop chat clients

The API Keys page offers one-click configuration for chat clients such as Cherry Studio and others; the Playground lets you try any model in the browser without writing code.

Billing and usage

• Prepaid, pay as you go. You top up a balance in US dollars and every request is deducted from it; there is no subscription. Top-ups and redeem codes are in Wallet.
• Prices. The Model Square (no account needed) shows, for each model, the Afri Nexus price next to the provider’s official list price and the discount of the model’s key group; Details lists every price tier, endpoint and a ready-to-run request. The group descriptions (for example “Claude · 29% of list price”) summarise the same discount.
• Text models are billed per token: input tokens, output tokens (including reasoning tokens) and, where the provider supports caching, cached input at the cache-read rate and cache writes at the cache-write rate. Token counts come from the provider’s response and may include provider-side system tokens, which show up as (mostly cached) input tokens in your logs. Some providers price long prompts higher (OpenAI above 272K tokens, xAI from 200K, MiniMax above 512K, Haiku 5.5 above 100K), exactly as on their own lists.
• Image models are billed per image, by resolution tier (1K / 2K / 4K).
• Video models are billed per second (Wan, Kling) or per million video tokens (Seedance), with a reservation at submission and a settlement at completion.
• Usage logs. Usage logs list every request with its model, tokens and cost; filter by key to attribute spend to a project. The dashboard charts spend over time.
• Per-key limits. A key can carry its own spending limit and expiry date; when the limit or your balance is exhausted, requests fail with HTTP 403 until you top up.

Errors and limits

Errors use the OpenAI error envelope:

{
  "error": {
    "message": "...",
    "type": "...",
    "code": "..."
  }
}

Limits

• 100 seconds per non-streaming HTTP request. Streaming responses are not affected as long as data keeps flowing.
• Images: one image per request (n = 1).
• Video: durations and resolutions per model as listed in Video generation; reference images and videos must be public URLs.
• Context windows and output limits are the provider’s; see the provider reference.

FAQ and support