API هوش مصنوعی

مستندات

  1. با شماره موبایل وارد شوید.
  2. از صفحه‌ی خرید اعتبار یک بسته بخرید.
  3. در داشبورد یک کلید API بسازید (کلید فقط یک بار نمایش داده می‌شود).
  4. در برنامه‌ی خود base_url را عوض کنید، کلید را وارد کنید و نام مدل را بنویسید.

آدرس‌ها و احراز هویت

فرمتbase_urlمسیر
OpenAIhttps://api.2928.ir/v1/chat/completions
Anthropichttps://api.2928.ir/v1/messages
لیست مدل‌هاhttps://api.2928.ir/v1/models
کدام آدرس؟ ابزارهای OpenAI (Cursor، کتابخانه‌ی openai و...) آدرس را با /v1 می‌خواهند: https://api.2928.ir/v1. ابزارهای Anthropic (اپ Claude، Claude Code، Anthropic SDK) خودشان /v1/messages را اضافه می‌کنند، پس آدرس را بدون /v1 وارد کنید: https://api.2928.ir.

کلید را در هدر Authorization: Bearer sk-... بفرستید. در فرمت Anthropic هدر x-api-key هم پذیرفته می‌شود. هر دو فرمت با همه‌ی مدل‌ها کار می‌کنند؛ یعنی می‌توانید GPT را با فرمت Anthropic یا Claude را با فرمت OpenAI صدا بزنید.

اتصال ابزارها

راهنمای قدم‌به‌قدم: Claude Code، Cursor، VS Code (Cline، Roo Code، Continue، Codex)، Codex CLI و Cherry Studio — برای ویندوز، مک و لینوکس، با کلید و مدل خودتان. ←
from openai import OpenAI

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

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "سلام!"}],
)
print(response.choices[0].message.content)

ابزارهای دیگر (Cline، Continue، Roo Code، LangChain، n8n، LobeChat و...) معمولاً گزینه‌ی «OpenAI Compatible» دارند: Base URL را https://api.2928.ir/v1 بگذارید، کلید را وارد کنید و نام مدل را بنویسید.

استریم

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

stream = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "یک شعر کوتاه بنویس"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Function Calling

پارامتر tools مثل API رسمی OpenAI کار می‌کند؛ برای GPT و Claude.

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "هوای تهران چطور است؟"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
)
print(response.choices[0].message.tool_calls)

تصویر

تصویر را به‌صورت base64 بفرستید. لینک مستقیم هم پشتیبانی می‌شود، ولی بعضی سایت‌ها دانلود خودکار را مسدود می‌کنند؛ base64 همیشه کار می‌کند.

import base64

image = base64.b64encode(open("photo.jpg", "rb").read()).decode()
response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "در این تصویر چه می‌بینی؟"},
        {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image}"}},
    ]}],
)

ساخت و ویرایش تصویر

مدل‌های gpt-image-2 و gpt-image-2.5-flare از روی متن تصویر می‌سازند یا تصویر شما را ویرایش می‌کنند؛ متن فارسی روی تصویر را هم درست می‌نویسند. هر تصویر قیمت ثابت دارد (در صفحه‌ی مدل‌ها) و ساخت آن معمولاً ۲۰ تا ۴۵ ثانیه طول می‌کشد.

import base64

# ساخت تصویر
result = client.images.generate(
    model="gpt-image-2",
    prompt="یک گربه‌ی قرمز روی صندلی آبی، تصویرسازی ساده",
    size="1024x1024",
)
open("cat.png", "wb").write(base64.b64decode(result.data[0].b64_json))

# ویرایش تصویر
result = client.images.edit(
    model="gpt-image-2",
    image=open("cat.png", "rb"),
    prompt="رنگ صندلی را سبز کن و بقیه را تغییر نده",
)
open("cat-green.png", "wb").write(base64.b64decode(result.data[0].b64_json))

مسیرها: POST /v1/images/generations و POST /v1/images/edits (فرمت OpenAI). زمان انتظار (timeout) برنامه‌تان را دست‌کم ۶۰ ثانیه بگذارید.

خطاها

کدمعنی
401کلید اشتباه است یا حذف شده.
403اعتبار حساب تمام شده؛ از صفحه‌ی خرید اعتبار تمدید کنید.
400درخواست نامعتبر (پارامتر اشتباه یا پیام خالی).
429تعداد درخواست زیاد است؛ کمی صبر کنید و دوباره بفرستید.
503 model_not_foundنام مدل اشتباه است؛ نام را دقیقاً از لیست پایین کپی کنید.
5xxخطای موقت سرور یا ارائه‌دهنده؛ دوباره تلاش کنید و در صورت تکرار وضعیت را در صفحه‌ی وضعیت ببینید.

نام مدل‌ها

Claude (Anthropic)

  • Claude Sonnet 5 پیشنهادی به‌صرفه
    claude-sonnet-5

    بهترین انتخاب برای بیشتر کارها: گفتگو، نوشتن و ترجمه، خلاصه‌سازی و برنامه‌نویسی روزمره؛ سریع و به‌صرفه.

    ورودی ×۱٫۵۰ · خروجی ×۷٫۵۰
  • Claude Opus 5.5 پیشنهادی برای برنامه‌نویسی
    claude-opus-5-5

    برنامه‌نویسی و کدنویسی قوی، رفع باگ‌های پیچیده، تحلیل دقیق و کار با Claude Code و Cursor.

    ورودی ×۳ · خروجی ×۱۵
  • Claude Opus 5
    claude-opus-5

    نسل قبلی Opus؛ برای برنامه‌نویسی و تحلیل‌های پیچیده. معمولاً Opus 5.5 انتخاب بهتری است.

    ورودی ×۳٫۷۵ · خروجی ×۱۸٫۷۵
  • Claude Haiku 4.5 ارزان سریع
    claude-haiku-4-5-20251001

    سریع‌ترین و ارزان‌ترین Claude؛ برای کارهای ساده و پرتعداد مثل دسته‌بندی، پاسخ کوتاه و ربات‌ها.

    ورودی ×۰٫۷۵ · خروجی ×۳٫۷۵

GPT (OpenAI)

  • GPT-6.1 Sol ارزان سریع
    gpt-6.1-sol

    ارزان‌ترین GPT؛ برای گفتگوی روزمره، سؤال‌وجواب و نوشتن متن‌های کوتاه.

    ورودی ×۱٫۵۰ · خروجی ×۷٫۵۰
  • GPT-5.5
    gpt-5.5

    GPT همه‌کاره برای استدلال و حل مسئله. هر پیام هزینه‌ی پایه‌ی بیشتری دارد؛ برای کارهای ساده GPT-6.1 Sol به‌صرفه‌تر است.

    ورودی ×۳٫۷۵ · خروجی ×۲۲٫۵۰

ساخت و ویرایش تصویر (GPT Image)

  • GPT Image 2.5 Sunburst
    gpt-image-2.5-sunburst
    هر تصویر ۶۸٬۰۲۵ توکن (≈ ۱۲٬۳۰۰ تومان)
  • GPT Image 2.5 Flare متن فارسی
    gpt-image-2.5-flare

    ساخت و ویرایش تصویر با حال‌وهوای ایرانی و نوشتن متن فارسی روی تصویر.

    هر تصویر ۶۸٬۰۲۵ توکن (≈ ۱۲٬۳۰۰ تومان)
  • GPT Image 2 پیشنهادی سریع
    gpt-image-2

    ساخت تصویر از متن و ویرایش عکس (تغییر رنگ، اضافه کردن یا حذف چیزی)؛ سریع‌ترین مدل تصویر.

    هر تصویر ۶۸٬۰۲۵ توکن (≈ ۱۲٬۳۰۰ تومان)

ضریب یعنی به ازای هر توکنِ مدل چند توکن از اعتبار شما کم می‌شود. مثلاً «ورودی ×۲» یعنی هر ۱٬۰۰۰ توکن ورودی، ۲٬۰۰۰ توکن اعتبار مصرف می‌کند. مدل‌های تصویر قیمت ثابت دارند: ساخت یا ویرایش هر تصویر همان مقدار ثابت را مصرف می‌کند (قیمت تومانی با نرخ روز تتر کمی تغییر می‌کند).