📚 مستندات API

این API کاملاً سازگار با فرمت OpenAI است. هر ابزار یا SDK که با OpenAI کار می‌کند — بدون تغییر کد — با این سرویس هم کار می‌کند. فقط base_url و API key را عوض کنید.

🌐 Base URL

🔑 احراز هویت

همه درخواست‌ها باید هدر Authorization داشته باشند:

Authorization: Bearer YOUR_API_KEYکپی

🤖 لیست مدل‌ها

لیست تمام مدل‌های فعال را برمی‌گرداند.

curl BASE_URL/v1/models \
  -H "Authorization: Bearer YOUR_KEY"کپی

from openai import OpenAI
client = OpenAI(api_key="YOUR_KEY", base_url="BASE_URL/v1")
for m in client.models.list(): print(m.id)کپی

import OpenAI from "openai";
const c = new OpenAI({ apiKey:"YOUR_KEY", baseURL:"BASE_URL/v1" });
const list = await c.models.list();
console.log(list.data.map(m=>m.id));کپی

💬 Chat Completions

پارامترها

curl BASE_URL/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role":"system","content":"You are helpful."},
      {"role":"user","content":"سلام!"}
    ]
  }'کپی

from openai import OpenAI
client = OpenAI(api_key="YOUR_KEY", base_url="BASE_URL/v1")
res = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role":"user","content":"سلام!"}]
)
print(res.choices[0].message.content)کپی

import OpenAI from "openai";
const c = new OpenAI({ apiKey:"YOUR_KEY", baseURL:"BASE_URL/v1" });
const res = await c.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role:"user", content:"سلام!" }]
});
console.log(res.choices[0].message.content);کپی

<?php
$ch = curl_init("BASE_URL/v1/chat/completions");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_KEY",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "model" => "gpt-4o",
    "messages" => [["role"=>"user","content"=>"سلام!"]]
  ])
]);
$r = json_decode(curl_exec($ch),true);
echo $r['choices'][0]['message']['content'];کپی

⚡ Streaming

با "stream": true پاسخ به صورت Server-Sent Events دریافت می‌شود.

from openai import OpenAI
client = OpenAI(api_key="YOUR_KEY", base_url="BASE_URL/v1")
with client.chat.completions.stream(
    model="gpt-4o",
    messages=[{"role":"user","content":"یه داستان کوتاه بنویس"}]
) as s:
    for t in s.text_stream:
        print(t, end="", flush=True)کپی

import OpenAI from "openai";
const c = new OpenAI({ apiKey:"YOUR_KEY", baseURL:"BASE_URL/v1" });
const s = await c.chat.completions.stream({
  model:"gpt-4o",
  messages:[{role:"user",content:"یه داستان بنویس"}]
});
for await (const chunk of s) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}کپی

🧪 نمونه‌های کامل

LangChain (Python)

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o", api_key="YOUR_KEY", base_url="BASE_URL/v1")
print(llm.invoke("سلام").content)کپی

fetch مستقیم (JS)

const res = await fetch("BASE_URL/v1/chat/completions", {
  method:"POST",
  headers:{"Authorization":"Bearer YOUR_KEY","Content-Type":"application/json"},
  body: JSON.stringify({model:"gpt-4o",messages:[{role:"user",content:"Hi!"}]})
});
const d = await res.json();
console.log(d.choices[0].message.content);کپی

LiteLLM (Python)

import litellm
res = litellm.completion(
    model="openai/gpt-4o",
    api_key="YOUR_KEY", api_base="BASE_URL/v1",
    messages=[{"role":"user","content":"سلام!"}]
)
print(res.choices[0].message.content)کپی

🧠 Hermes Agent

Hermes Agent از پروایدرهای سازگار با OpenAI پشتیبانی می‌کند. دو روش اضافه کردن:

روش ۱ — از طریق config.yaml

model:
  provider: openai-api
  model: gpt-4o          # هر model_id از /v1/models
  api_key: YOUR_KEY
  base_url: BASE_URL/v1کپی

روش ۲ — دستور hermes config

hermes config set model.provider openai-api
hermes config set model.base_url BASE_URL/v1
hermes config set model.api_key YOUR_KEY
hermes config set model.model gpt-4oکپی

تنظیم subagent جداگانه

hermes config set delegation.provider openai-api
hermes config set delegation.base_url BASE_URL/v1
hermes config set delegation.api_key YOUR_KEY
hermes config set delegation.model gpt-4oکپی

🔀 OpenRouter

در OpenRouter می‌توانید این API را به عنوان یک پروایدر سفارشی تعریف کنید.

استفاده در کد با OpenRouter SDK

from openai import OpenAI

# مستقیم از این API بدون OpenRouter
client = OpenAI(
    api_key="YOUR_KEY",
    base_url="BASE_URL/v1"
)
# اگر از OpenRouter به عنوان gateway استفاده می‌کنید:
# base_url="https://openrouter.ai/api/v1"
# و در headers پروایدر سفارشی را مشخص کنیدکپی

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_KEY",
  baseURL: "BASE_URL/v1",
  defaultHeaders: {
    "HTTP-Referer": "https://yoursite.com",
    "X-Title": "Your App"
  }
});

const res = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "سلام!" }]
});کپی

🃏 SillyTavern

SillyTavern از OpenAI-compatible API پشتیبانی کاملی دارد.

1. در SillyTavern بروید به API Connections
2. نوع API را Chat Completion انتخاب کنید
3. سورس را روی OpenAI بگذارید
4. در فیلد Custom Endpoint (Base URL) آدرس زیر را وارد کنید:

BASE_URL/v1کپی

5. در فیلد API Key کلید خود را وارد کنید
6. روی Connect کلیک کنید — مدل‌ها خودکار لود می‌شوند

💬 NextChat (ChatGPT-Next-Web)

NextChat از custom endpoint پشتیبانی می‌کند.

1. وارد NextChat شوید و روی آیکون ⚙️ (Settings) کلیک کنید
2. در بخش OpenAI API Key کلید API خود را وارد کنید
3. در فیلد API Host / Custom Endpoint آدرس زیر را وارد کنید:

BASE_URLکپی

⛓️ LangChain / LlamaIndex

from langchain_openai import ChatOpenAI, OpenAIEmbeddings

# Chat
llm = ChatOpenAI(
    model="gpt-4o",
    api_key="YOUR_KEY",
    base_url="BASE_URL/v1"
)
response = llm.invoke("سلام، خودت رو معرفی کن")
print(response.content)

# با پیام‌های سیستمی
from langchain_core.messages import HumanMessage, SystemMessage
messages = [
    SystemMessage(content="You are a helpful assistant."),
    HumanMessage(content="سلام!")
]
print(llm.invoke(messages).content)کپی

import { ChatOpenAI } from "@langchain/openai";

const llm = new ChatOpenAI({
  model: "gpt-4o",
  openAIApiKey: "YOUR_KEY",
  configuration: {
    baseURL: "BASE_URL/v1"
  }
});

const res = await llm.invoke("سلام!");
console.log(res.content);کپی

from llama_index.llms.openai import OpenAI
from llama_index.core import Settings

llm = OpenAI(
    model="gpt-4o",
    api_key="YOUR_KEY",
    api_base="BASE_URL/v1"
)
Settings.llm = llm

# استفاده مستقیم
response = llm.complete("سلام!")
print(response.text)کپی

❌ کدهای خطا

❓ سوالات متداول

با OpenAI SDK سازگار است؟

بله — فقط base_url را عوض کنید. هیچ تغییر دیگری لازم نیست.

Function Calling پشتیبانی می‌شود؟

بله، در صورتی که مدل انتخابی از آن پشتیبانی کند.

Vision (تصویر) چطور؟

مدل‌های vision از آرایه content با image_url پشتیبانی می‌کنند — دقیقاً مثل OpenAI.

API key را کجا نگه دارم؟

# .env
API_KEY=your_key_here

# Python
import os; api_key = os.environ["API_KEY"]کپی