مستندات کامل API

مستندات درواره

درواره کاملا سازگار با API استاندارد OpenAI است. فقط کافیست base_url را تغییر دهید.

Base URL: api.darvareh.ir/v1
OpenAI-Compatible
+300 Models

شروع سریع

در سه مرحله ساده با درواره شروع کنید. نیازی به SDK خاصی نیست — از OpenAI SDK استفاده کنید.

۱

نصب SDK

SDK موردنظرتان را نصب کنید

۲

تنظیم Base URL

آدرس API درواره را وارد کنید

۳

ارسال درخواست

مثل OpenAI درخواست بزنید

نصب

bash
pip install openai

اولین درخواست

python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.darvareh.ir/v1",
    api_key="sk-darvareh-YOUR_KEY"
)

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "سلام! خودت رو معرفی کن."}
    ]
)

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

احراز هویت

دو نوع احراز هویت

API Key (برای مدل‌ها)

برای endpoint‌های /v1/* از کلید API استفاده کنید. فرمت: sk-darvareh-...

JWT Token (برای مدیریت)

برای endpoint‌های /api/v1/* (مدیریت کلیدها، اعتبار و...) از JWT استفاده کنید.

نحوه استفاده از API Key

http
Authorization: Bearer sk-darvareh-YOUR_KEY

کلید API فقط یک‌بار هنگام ساخت نمایش داده می‌شود. آن را در جای امنی ذخیره کنید.

Chat Completions

POST/v1/chat/completionsارسال درخواست چت و دریافت پاسخ

پارامترهای درخواست

پارامترنوعالزامیتوضیحات
modelstringالزامیشناسه مدل (مثلا openai/gpt-4o)
messagesarrayالزامیآرایه‌ای از پیام‌ها با role و content
temperaturefloatاختیاریدمای نمونه‌برداری (0 تا 2)
top_pfloatاختیارینمونه‌برداری nucleus (0 تا 1)
max_tokensintegerاختیاریحداکثر توکن‌های پاسخ
streambooleanاختیاریفعال‌سازی streaming (پیش‌فرض: false)
nintegerاختیاریتعداد پاسخ‌های تولیدشده
stopstring | arrayاختیاریرشته‌های توقف تولید
presence_penaltyfloatاختیاریجریمه حضور (-2 تا 2)
frequency_penaltyfloatاختیاریجریمه تکرار (-2 تا 2)
toolsarrayاختیاریتعریف ابزارها (Function Calling)
tool_choicestring | objectاختیارینحوه انتخاب ابزار
response_formatobjectاختیاریفرمت پاسخ (مثلا JSON mode)
seedintegerاختیاریبذر تصادفی برای تکرارپذیری

نمونه درخواست و پاسخ

python
response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4",
    messages=[
        {"role": "system", "content": "You are a senior Python developer."},
        {"role": "user", "content": "یک تابع فیبوناچی بهینه بنویس."}
    ],
    temperature=0.7,
    max_tokens=1024
)

print(response.choices[0].message.content)
print(f"Tokens used: {response.usage.total_tokens}")

پاسخ

json
{
  "id": "chatcmpl-abc123...",
  "object": "chat.completion",
  "created": 1709123456,
  "model": "anthropic/claude-sonnet-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 156,
    "total_tokens": 198
  }
}

ورودی چندوجهی (Multimodal)

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

python
# Vision — ارسال تصویر
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "این تصویر چیست؟"},
            {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
        ]
    }]
)

# Function Calling — فراخوانی ابزار
response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "هوای تهران چطوره؟"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"}
                },
                "required": ["city"]
            }
        }
    }]
)

Streaming

با فعال کردن stream: true پاسخ به صورت لحظه‌ای (SSE) دریافت می‌شود.

python
stream = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "یک داستان کوتاه بنویس."}],
    stream=True
)

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

# Async streaming
import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI(
    base_url="https://api.darvareh.ir/v1",
    api_key="sk-darvareh-YOUR_KEY"
)

async def stream_response():
    stream = await async_client.chat.completions.create(
        model="openai/gpt-4o",
        messages=[{"role": "user", "content": "یک شعر بنویس."}],
        stream=True
    )
    async for chunk in stream:
        content = chunk.choices[0].delta.content
        if content:
            print(content, end="", flush=True)

asyncio.run(stream_response())

فرمت Chunk

json
data: {"id":"chatcmpl-abc...","object":"chat.completion.chunk","created":1709123456,"model":"openai/gpt-4o","choices":[{"index":0,"delta":{"content":"سلام"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc...","object":"chat.completion.chunk","created":1709123456,"model":"openai/gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":10,"completion_tokens":50,"total_tokens":60}}

data: [DONE]

Text Completions
Legacy

POST/v1/completionsتکمیل متن (API قدیمی)
پارامترنوعالزامیتوضیحات
modelstringالزامیشناسه مدل
promptstring | arrayالزامیمتن ورودی برای تکمیل
max_tokensintegerاختیاریحداکثر توکن (پیش‌فرض: 16)
temperaturefloatاختیاریدمای نمونه‌برداری
streambooleanاختیاریفعال‌سازی streaming
stopstring | arrayاختیاریرشته‌های توقف
suffixstringاختیاریپسوند (برای infill)
python
response = client.completions.create(
    model="openai/gpt-3.5-turbo-instruct",
    prompt="def fibonacci(n):",
    max_tokens=200,
    temperature=0
)

print(response.choices[0].text)

Embeddings

POST/v1/embeddingsتولید بردارهای embedding از متن
پارامترنوعالزامیتوضیحات
modelstringالزامیمدل embedding (مثلا openai/text-embedding-3-small)
inputstring | arrayالزامیمتن یا آرایه‌ای از متن‌ها
encoding_formatstringاختیاریفرمت خروجی: float یا base64 (پیش‌فرض: float)
dimensionsintegerاختیاریتعداد ابعاد خروجی
python
response = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input="سلام دنیا"
)

embedding = response.data[0].embedding
print(f"Dimensions: {len(embedding)}")
print(f"First 5: {embedding[:5]}")

# Batch embeddings
response = client.embeddings.create(
    model="openai/text-embedding-3-small",
    input=["متن اول", "متن دوم", "متن سوم"]
)

for item in response.data:
    print(f"[{item.index}] {len(item.embedding)} dims")

پاسخ

json
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.0023, -0.0094, 0.0156, ...],
      "index": 0
    }
  ],
  "model": "openai/text-embedding-3-small",
  "usage": {
    "prompt_tokens": 4,
    "total_tokens": 4
  }
}

Image Generation

POST/v1/images/generationsتولید تصویر از متن
پارامترنوعالزامیتوضیحات
promptstringالزامیتوصیف تصویر موردنظر
modelstringاختیاریمدل تولید تصویر
nintegerاختیاریتعداد تصاویر (پیش‌فرض: 1)
sizestringاختیاریاندازه تصویر (پیش‌فرض: 1024x1024)
qualitystringاختیاریکیفیت: standard یا hd
response_formatstringاختیاریفرمت: url یا b64_json
stylestringاختیاریسبک: vivid یا natural
python
response = client.images.generate(
    model="openai/dall-e-3",
    prompt="A futuristic city at sunset, cyberpunk style",
    size="1024x1024",
    quality="hd",
    n=1
)

image_url = response.data[0].url
print(image_url)

Video Generation

تولید و ویرایش ویدیو با استفاده از مدل‌هایی مانند google/veo-3.0، minimax/video-01 و سایر مدل‌های پشتیبانی شده. درخواست‌ها از طریق endpoint استاندارد Chat Completions ارسال می‌شوند.

POST/v1/chat/completionsتولید ویدیو از طریق Chat Completions API
پارامترنوعالزامیتوضیحات
modelstringالزامیشناسه مدل ویدیو (مثلا google/veo-3.0)
messagesarrayالزامیپیام‌ها شامل توصیف ویدیو
max_tokensintegerاختیاریحداکثر توکن خروجی
python
# تولید ویدیو با Chat Completions API
response = client.chat.completions.create(
    model="google/veo-3.0",
    messages=[
        {
            "role": "user",
            "content": "Generate a 5-second video of a cat playing with a ball in a garden"
        }
    ]
)

# خروجی شامل URL ویدیو تولید شده
print(response.choices[0].message.content)

مدل‌های ویدیو پشتیبانی شده

مدلارائه‌دهندهتوضیحات
google/veo-3.0Googleمدل پیشرفته تولید ویدیو
minimax/video-01MiniMaxتولید ویدیو کوتاه
kling-ai/kling-video-v2Kling AIتولید ویدیوی باکیفیت
luma/ray-2Luma AIتولید ویدیو سه‌بعدی

ویرایش ویدیو (Image-to-Video)

برای تبدیل تصویر به ویدیو، تصویر را به صورت URL در محتوای پیام ارسال کنید:

python
response = client.chat.completions.create(
    model="google/veo-3.0",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Animate this image with gentle wind movement"},
                {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
            ]
        }
    ]
)

Audio Transcription

POST/v1/audio/transcriptionsتبدیل صوت به متن
پارامترنوعالزامیتوضیحات
filefileالزامیفایل صوتی (wav, mp3, webm, ogg, flac, aac, m4a)
modelstringاختیاریمدل (پیش‌فرض: google/gemini-2.5-flash-preview)
promptstringاختیاریراهنمای رونوشت
languagestringاختیاریزبان صوت (مثلا fa, en)
temperaturefloatاختیاریدمای نمونه‌برداری

حداکثر حجم فایل: ۲۵ مگابایت. فرمت‌های پشتیبانی‌شده: wav, mp3, webm, ogg, flac, aac, m4a

python
audio_file = open("recording.mp3", "rb")

transcript = client.audio.transcriptions.create(
    file=audio_file,
    model="google/gemini-2.5-flash-preview",
    language="fa"
)

print(transcript.text)

Text-to-Speech

POST/v1/audio/speechتبدیل متن به صوت
پارامترنوعالزامیتوضیحات
modelstringالزامیمدل TTS
inputstringالزامیمتن برای تبدیل به صوت
voicestringالزامیصدای مورد نظر (alloy, echo, fable, onyx, nova, shimmer)
response_formatstringاختیاریفرمت خروجی: mp3, opus, aac, flac, wav, pcm
speedfloatاختیاریسرعت (0.25 تا 4.0، پیش‌فرض: 1.0)
python
response = client.audio.speech.create(
    model="openai/tts-1",
    voice="alloy",
    input="سلام! من یک دستیار هوشمند هستم."
)

response.stream_to_file("output.mp3")

Moderations

POST/v1/moderationsبررسی محتوا از نظر مطابقت با سیاست‌ها
پارامترنوعالزامیتوضیحات
inputstring | arrayالزامیمتن یا آرایه‌ای از متن‌ها برای بررسی
modelstringاختیاریمدل (پیش‌فرض: omni-moderation-latest)
python
response = client.moderations.create(
    input="متن مورد نظر برای بررسی"
)

result = response.results[0]
print(f"Flagged: {result.flagged}")
print(f"Categories: {result.categories}")

Models

GET/v1/modelsلیست تمام مدل‌های در دسترس

لیست مدل‌ها بر اساس کلید API فیلتر می‌شود. اگر کلید شما محدود به مدل‌های خاصی باشد، فقط همان‌ها نمایش داده می‌شوند.

python
models = client.models.list()

for model in models.data:
    print(f"{model.id} — {model.owned_by}")

پاسخ

json
{
  "object": "list",
  "data": [
    {
      "id": "openai/gpt-4o",
      "object": "model",
      "owned_by": "openai",
      "name": "GPT-4o",
      "context_length": 128000,
      "capabilities": {
        "input_modalities": ["text", "image"],
        "output_modalities": ["text"]
      },
      "pricing": {
        "prompt": "0.0000025",
        "completion": "0.00001"
      },
      "max_completion_tokens": 16384
    }
  ]
}

سازگاری با فریمورک‌ها

درواره با تمام فریمورک‌ها و کتابخانه‌هایی که از API استاندارد OpenAI پشتیبانی می‌کنند سازگار است. فقط کافیست base_url را تغییر دهید.

python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="openai/gpt-4o",
    base_url="https://api.darvareh.ir/v1",
    api_key="sk-darvareh-YOUR_KEY",
    temperature=0.7
)

response = llm.invoke("سلام! خودت رو معرفی کن.")
print(response.content)

# With streaming
for chunk in llm.stream("یک داستان کوتاه بنویس."):
    print(chunk.content, end="")

# Embeddings
from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(
    model="openai/text-embedding-3-small",
    base_url="https://api.darvareh.ir/v1",
    api_key="sk-darvareh-YOUR_KEY"
)

result = embeddings.embed_query("سلام دنیا")
print(f"Dimensions: {len(result)}")

محدودیت نرخ

محدودیت نرخ بر اساس هر کلید API اعمال می‌شود. می‌توانید هنگام ساخت کلید، محدودیت‌های RPM و TPM را تنظیم کنید.

محدودیتتوضیحاتقابل تنظیم
RPMتعداد درخواست در دقیقهبله — هنگام ساخت کلید API
TPMتعداد توکن در دقیقهبله — هنگام ساخت کلید API

در صورت رسیدن به محدودیت، خطای 429 دریافت خواهید کرد. صبر کنید و دوباره تلاش کنید یا محدودیت کلید را افزایش دهید.

خطاها

تمام خطاها در فرمت استاندارد OpenAI برگردانده می‌شوند:

json
{
  "error": {
    "message": "توضیح خطا",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

کدهای وضعیت HTTP

کدنوعتوضیحات
400invalid_request_errorدرخواست نامعتبر — پارامترهای ارسالی اشتباه است
401authentication_errorاحراز هویت ناموفق — کلید API نامعتبر یا منقضی شده
402insufficient_fundsاعتبار ناکافی — حساب خود را شارژ کنید
403permission_errorمدل برای این کلید مجاز نیست
413file_too_largeحجم فایل بیش از حد مجاز
429rate_limit_errorمحدودیت نرخ — تعداد درخواست‌ها بیش از حد مجاز
500server_errorخطای داخلی سرور

مدیریت خطا در کد

python
from openai import OpenAI, APIError, AuthenticationError, RateLimitError

client = OpenAI(
    base_url="https://api.darvareh.ir/v1",
    api_key="sk-darvareh-YOUR_KEY"
)

try:
    response = client.chat.completions.create(
        model="openai/gpt-4o",
        messages=[{"role": "user", "content": "سلام!"}]
    )
except AuthenticationError:
    print("کلید API نامعتبر است")
except RateLimitError:
    print("محدودیت نرخ — کمی صبر کنید")
except APIError as e:
    if e.status_code == 402:
        print("اعتبار ناکافی — حساب را شارژ کنید")
    elif e.status_code == 403:
        print("این مدل برای کلید شما مجاز نیست")
    else:
        print(f"خطا: {e.message}")

API مدیریت

endpoint‌های مدیریت از احراز هویت JWT استفاده می‌کنند. ابتدا با /api/v1/auth/login توکن بگیرید.

احراز هویت

متدمسیرتوضیحات
POST/api/v1/auth/registerثبت‌نام کاربر جدید
POST/api/v1/auth/loginورود و دریافت access/refresh token
POST/api/v1/auth/refreshتمدید توکن با refresh token
POST/api/v1/auth/logoutخروج و ابطال توکن
GET/api/v1/auth/meاطلاعات کاربر فعلی
bash
# ثبت‌نام
curl -X POST https://api.darvareh.ir/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "strongpass123"}'

# ورود
curl -X POST https://api.darvareh.ir/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "strongpass123"}'

# پاسخ ورود:
# {
#   "access_token": "eyJ...",
#   "refresh_token": "eyJ...",
#   "token_type": "bearer",
#   "expires_in": 1800
# }

مدیریت کلیدهای API

متدمسیرتوضیحات
GET/api/v1/keysلیست کلیدهای API
POST/api/v1/keysساخت کلید جدید
DELETE/api/v1/keys/{id}حذف کلید
GET/api/v1/keys/{id}/usageآمار مصرف کلید

ساخت کلید API

bash
curl -X POST https://api.darvareh.ir/api/v1/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "rate_limit_rpm": 60,
    "rate_limit_tpm": 100000,
    "allowed_models": ["openai/gpt-4o", "anthropic/claude-sonnet-4"]
  }'

# پاسخ:
# {
#   "id": "...",
#   "key": "sk-darvareh-abc123...",  ← فقط یکبار نمایش داده می‌شود!
#   "key_prefix": "sk-darvareh-abc1",
#   "name": "Production Key",
#   "rate_limit_rpm": 60,
#   "rate_limit_tpm": 100000,
#   "allowed_models": {"models": ["openai/gpt-4o", "anthropic/claude-sonnet-4"]},
#   "is_active": true,
#   "total_requests": 0,
#   "total_tokens": 0,
#   "total_spent": "0"
# }

نکته: اگر allowed_models را خالی بگذارید، کلید به تمام مدل‌ها دسترسی خواهد داشت.

اعتبار و صورتحساب

متدمسیرتوضیحات
GET/api/v1/billing/balanceموجودی فعلی
GET/api/v1/billing/transactionsتاریخچه تراکنش‌ها

نکته: تمام مبالغ به تومان نمایش داده می‌شوند.

bash
curl https://api.darvareh.ir/api/v1/billing/balance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# پاسخ:
# {
#   "user_id": "...",
#   "balance": "8,750,000",
#   "total_credits_used": "26,250,000"
# }

نحوه محاسبه هزینه

  • هزینه بر اساس تعداد توکن‌های مصرفی (ورودی + خروجی) محاسبه می‌شود
  • قیمت هر مدل متفاوت است — از صفحه مدل‌ها قیمت‌ها را ببینید
  • هزینه به صورت اتمیک از موجودی کسر می‌شود — هیچ درخواستی بدون اعتبار کافی پردازش نمی‌شود
  • در صورت بروز خطای سرور، هزینه به حساب برگردانده می‌شود

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

همین الان حساب بسازید و با یک کلید API به بیش از ۳۰۰ مدل دسترسی داشته باشید.