KIVXA

معرفی KIVXA AI Gateway

Architecture

پلتفرم KIVXA یک AI API Gateway مدرن و پرسرعت است (مشابه زیرساخت‌هایی چون OpenRouter و Hugging Face Inference) که به عنوان لایه واسط مرکزی میان کدهای نرم‌افزاری شما و ارائه‌دهندگان مطرح هوش مصنوعی جهان عمل می‌کند.

یک کلید، صدها مدل

دیگر نیازی به افتتاح حساب در چندین شرکت خارجی و پرداخت‌های مجزا نیست. با یک API Key به همه چیز متصل شوید.

سازگاری ۱۰۰٪ با OpenAI

تمام کتابخانه‌ها و SDKهای رسمی OpenAI بدون کوچک‌ترین تغییری در بدنه درخواست‌ها پشتیبانی می‌شوند.

پایداری و Fallback هوشمند

گیت‌وی با مسیریابی بهینه کمترین تاخیر (Latency) را برای کاربران در داخل و خارج از کشور فراهم می‌سازد.

شروع سریع در ۱ دقیقه

Quick Start

برای اتصال به KIVXA تنها کافیست Base URL را به آدرس زیر تغییر داده و API Key دریافتی از پنل KIVXA را قرار دهید:

Quickstart Example

from openai import OpenAI

# تنها با تغییر base_url و قرار دادن کلید اختصاصی KIVXA
client = OpenAI(
    base_url="https://api.kivxa.com/api/v1",
    api_key="sk-live-kivxa_your_api_key_here"
)

response = client.chat.completions.create(
    model="deepseek/deepseek-chat-v3.1", # یا هر مدلی نظیر openai/gpt-4o
    messages=[
        {"role": "system", "content": "You are a helpful programming assistant."},
        {"role": "user", "content": "یک تابع فیبوناچی بهینه در پایتون بنویس."}
    ],
    temperature=0.7
)

print(response.choices[0].message.content)

Base URL و ساختار آدرس‌ها

Base Endpoint

تمامی درخواست‌های سازگار با استاندارد هوش مصنوعی از طریق پیش‌وند /api/v1 انجام می‌پذیرد.

Production Gateway URL

https://api.kivxa.com/api/v1

پشتیبانی از پروتکل امن HTTPS و HTTP/2 با پایین‌ترین Latency شبکه.

پشتیبانی کامل از CORS برای فراخوانی مستقیم از سمت فرانت‌اند یا وب اپلیکیشن‌ها.

احراز هویت و مدیریت API Key

Bearer Auth

برای ارسال درخواست به کلیه سرویس‌های هوش مصنوعی، ارسال کلید در هدر استاندارد Authorization الزامی است:

HTTP Request Headers

Authorization: Bearer sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

نکات کلیدی امنیت API Key

کلیدهای معتبر KIVXA همواره با پیشوند sk-live- شروع می‌شوند.
کلید شما محرمانه بوده و در دیتابیس سرور به صورت هش رمزنگاری‌شده (SHA-256) نگهداری می‌شود.
هرگز کلید را در ریپازیتوری‌های گیت‌هاب عمومی یا کدهای کلاینت بدون پروکسی قرار ندهید؛ از Environment Variables استفاده کنید.

Chat Completions API

Core Endpoint

POST/api/v1/chat/completions

تولید پاسخ متنی بر پایه تاریخچه گفتگو

این اندپوینت هسته مرکزی تعامل با مدل‌های هوش مصنوعی مکالمه‌ای و استدلالی است. ساختار درخواست دقیقاً منطبق بر استانداردهای OpenAI Specification است.

پارامترهای بدنه درخواست (Request Body)

فیلد (Parameter)	نوع (Type)	وضعیت	توضیحات و مقادیر
model	string	اجباری	شناسه مدل هدف به فرمت provider/model-id (مثال: openai/gpt-4o, deepseek/deepseek-chat-v3.1, anthropic/claude-3.5-sonnet)
messages	array	اجباری	آرایه‌ای از آبجکت‌های پیام شامل role (system \| user \| assistant \| tool) و content متنی.
stream	boolean	اختیاری	ارسال پاسخ به‌صورت استریم لحظه‌ای کاراکترها از طریق Server-Sent Events (SSE).پیش‌فرض: `false`
temperature	number	اختیاری	میزان خلاقیت یا قطعی بودن پاسخ بین 0.0 تا 2.0. مقادیر نزدیک به 0 برای کارهای تحلیلی و کدنویسی توصیه می‌شود.پیش‌فرض: `1.0`
max_tokens	integer	اختیاری	حداکثر سقف توکن‌های تولیدی در پاسخ مدل.
top_p	number	اختیاری	نمونه‌برداری هسته‌ای (Nucleus Sampling).پیش‌فرض: `1.0`
tools	array	اختیاری	فهرست توابع و ابزارهایی که مدل می‌تواند آن‌ها را فراخوانی کند (Function Calling).

نمونه ساختار پاسخ استاندارد (Response JSON)

HTTP 200 OK — JSON Response

{
  "id": "chatcmpl-kivxa-9b48f93e21",
  "object": "chat.completion",
  "created": 1720023412,
  "model": "deepseek/deepseek-chat-v3.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "سلام! من مدل هوش مصنوعی در پلتفرم KIVXA هستم. چگونه می‌توانم به شما کمک کنم؟"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 24,
    "total_tokens": 42
  }
}

Streaming با Server-Sent Events (SSE)

Realtime

در مواردی که نیاز به پاسخ فوری بدون منتظر ماندن برای پایان تولید کل متن دارید، با فرستادن "stream": true پاسخ را به صورت تکه‌تکه (Chunk) دریافت نمایید.

Streaming Implementation

from openai import OpenAI

client = OpenAI(
    base_url="https://api.kivxa.com/api/v1",
    api_key="sk-live-kivxa_your_api_key_here"
)

stream = client.chat.completions.create(
    model="anthropic/claude-3.5-sonnet",
    messages=[{"role": "user", "content": "یک داستان علمی تخیلی ۱۰۰ کلمه‌ای بگو."}],
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

فهرست و مشخصات مدل‌ها (Models API)

Public Endpoint

GET/api/v1/models

دریافت کاتالوگ مدل‌های فعال، ظرفیت کانتکست و نرخ قیمت‌گذاری

این اندپوینت نیاز به احراز هویت ندارد و کاتالوگ زنده‌ای از تمامی مدل‌های هوش مصنوعی فعال در شبکه را همراه با جزییات ارائه می‌دهد.

Get Models cURL

# دریافت کاتالوگ مدل‌ها
curl https://api.kivxa.com/api/v1/models

# صفحه‌بندی با پارامترهای اختیاری
curl "https://api.kivxa.com/api/v1/models?page=1&limit=50"

نمونه آبجکت مدل در خروجی:

Models JSON Response

{
  "success": true,
  "data": [
    {
      "id": "deepseek/deepseek-chat-v3.1",
      "name": "DeepSeek V3",
      "provider": "DeepSeek",
      "contextLength": 64000,
      "pricing": {
        "prompt": 0.27,
        "completion": 1.10
      },
      "capabilities": ["chat", "coding", "reasoning"]
    },
    {
      "id": "openai/gpt-4o",
      "name": "GPT-4o",
      "provider": "OpenAI",
      "contextLength": 128000,
      "pricing": {
        "prompt": 2.50,
        "completion": 10.00
      },
      "capabilities": ["chat", "vision", "multimodal", "tools"]
    }
  ]
}

Function Calling & ابزارهای خارجی

Advanced

مدل‌های مجهز به قابلیت Tools (نظیر GPT-4o، Claude 3.5 Sonnet و Gemini 1.5 Pro) می‌توانند پارامترهای مشخصی را بر اساس اسکیما استخراج کرده و به سیستم شما اعلام نمایند.

Tool Calling with Python

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "دریافت وضعیت آب و هوای یک شهر",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "نام شهر، مثلاً Tehran"},
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
            },
            "required": ["location"]
        }
    }
}]

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "هوای تهران الان چطوره؟"}],
    tools=tools,
    tool_choice="auto"
)

tool_calls = response.choices[0].message.tool_calls
print(tool_calls)

نمونه کدهای کامل پیاده‌سازی

Multi-Language

کدهای زیر را می‌توانید مستقیماً کپی کرده و در پروژه‌های Backend یا Agent هوش مصنوعی خود استفاده کنید:

Full Integration Examples

// install: npm install axios
import axios from 'axios';

const API_KEY = process.env.API_KEY || 'sk-live-YOUR_KEY';

async function generateAIAnswer(userPrompt) {
  try {
    const { data } = await axios.post(
      'https://api.kivxa.com/api/v1/chat/completions',
      {
        model: 'deepseek/deepseek-chat-v3.1',
        messages: [
          { role: 'system', content: 'You are an expert software architect.' },
          { role: 'user', content: userPrompt }
        ],
        temperature: 0.3
      },
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );

    return data.choices[0].message.content;
  } catch (error) {
    console.error('KIVXA API Error:', error.response?.data || error.message);
    throw error;
  }
}

سازگاری با فریم‌ورک‌های LangChain, LlamaIndex و Cursor

Ecosystem

از آنجا که پروتکل ورودی و خروجی KIVXA کاملاً بر پروتکل رسمی OpenAI منطبق است، می‌توانید از کلیه ابزارها و فریم‌ورک‌های محبوب استفاده نمایید:

LangChain (Python)

LangChain Integration

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="anthropic/claude-3.5-sonnet",
    openai_api_base="https://api.kivxa.com/api/v1",
    openai_api_key="sk-live-YOUR_API_KEY"
)

result = llm.invoke("هوش مصنوعی چیست؟")
print(result.content)

Next.js Vercel AI SDK

Vercel AI SDK

import { createOpenAI } from '@ai-sdk/openai';
import { streamText } from 'ai';

const client = createOpenAI({
  baseURL: 'https://api.kivxa.com/api/v1',
  apiKey: process.env.API_KEY,
});

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: client('openai/gpt-4o-mini'),
    messages,
  });

  return result.toDataStreamResponse();
}

مدیریت خطاها و کدهای وضعیت HTTP

Error Handling

در صورت بروز هرگونه مشکل، خروجی‌های خطای KIVXA از ساختار استاندارد خطای OpenAI با وضعیت‌های HTTP مشخص پیروی می‌کند:

Standard Error Payload

{
  "error": {
    "message": "Invalid API key provided. Check your key at https://kivxa.com/dashboard/apikeys",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}

کد وضعیت	عنوان خطا	دلیل و راهکار رفع
400	Bad Request	بدنه ارسالی نامعتبر است یا فیلد اجباری messages/model ارسال نشده است.
401	Unauthorized	کلید ارسالی در هدر وجود ندارد، منقضی شده یا اشتباه وارد شده است.
402	Payment Required	اعتبار حساب یا کیف‌پول شما کافی نیست. لطفا از کنسول اقدام به شارژ نمایید.
404	Model Not Found	شناسه مدل وارد شده در سیستم یافت نشد یا در دسترس نیست.
429	Rate Limit Exceeded	تعداد درخواست‌ها بیش از سقف مجاز بر دقیقه (RPM/TPM) فراتر رفته است.
500 / 502	Provider Gateway Error	مشکل موقت در زیرساخت اصلی مدل مورد نظر؛ ارسال مجدد با سازوکار Exponential Backoff توصیه می‌شود.

توصیه‌های فنی و پرسش‌های پرتکرار

FAQ

آیا برای تغییر مدل نیاز به تغییر کدنویسی دارم؟

خیر؛ زیبایی معماری KIVXA در همین است. تنها کافیست پارامتر "model" را به هر مدلی از Anthropic, DeepSeek, Google یا Meta تغییر دهید بدون اینکه ساختار درخواست عوض شود.

محاسبه هزینه و کسر اعتبار چگونه انجام می‌شود؟

محاسبه هزینه بر اساس فرمول استاندارد توکن‌های مصرفی (Prompt Tokens + Completion Tokens) با قیمت رسمی هر مدل سنجیده شده و لحظه‌ای از موجودی کسر می‌گردد. تمام تراکنش‌ها در بخش کیف پول داشبورد شفاف و قابل پیگیری هستند.

چگونه درخواست‌ها را در مواقع خطا مجدداً ارسال کنیم؟

پیشنهاد می‌شود برای خطاهای 429 و 50x از استراتژی Exponential Backoff with Jitter استفاده کنید (مثلا تاخیر ۱ ثانیه، ۲ ثانیه، ۴ ثانیه با مقداری تصادفی).

آماده شروع پیاده‌سازی هستید؟

در کمتر از 30 ثانیه کلید اختصاصی خود را بسازید و اولین درخواست چت را تست کنید.

ورود به کنسول API تست در محیط چت