مستندات API

شروع سریع

1. با شماره‌ی موبایل وارد شوید، در «شارژ اعتبار» برای مدل مورد نظرتان هر مبلغی که می‌خواهید شارژ کنید.
2. در «کلیدهای API» یک کلید بسازید (فقط یک بار نشان داده می‌شود).
3. کلید را در متغیر محیطی TOKENPROVIDER_API_KEY بگذارید (مثلاً export TOKENPROVIDER_API_KEY=...)، فهرست مدل‌های خودتان را بخوانید و اولین درخواست را بفرستید:

curl https://api.tokenprovider.ir/v1/models \
  -H "Authorization: Bearer $TOKENPROVIDER_API_KEY"

curl https://api.tokenprovider.ir/v1/chat/completions \
  -H "Authorization: Bearer $TOKENPROVIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "سلام!"}],
    "max_tokens": 200
  }'

ابزارهایی مثل Cursor، Cline، Continue، Aider و Open WebUI فقط «Base URL» و «API Key» می‌خواهند؛ تنظیمات آماده برای هر ابزار پس از ساخت کلید همان‌جا نمایش داده می‌شود.

احراز هویت

کلید را به یکی از دو شکل بفرستید: هدر Authorization: Bearer YOUR_API_KEY (سبک OpenAI) یا x-api-key: YOUR_API_KEY (سبک Anthropic). برای هر ابزار یا پروژه یک کلید جدا بسازید؛ هر کلید را می‌شود به مدل‌ها و IPهای مشخص، تاریخ انقضا و سقف سرعت محدود و هر لحظه باطل کرد. کلید را در کد سمت مرورگر یا مخزن عمومی نگذارید.

مدل‌ها

GET /v1/models فقط مدل‌هایی را برمی‌گرداند که هم اعتبارشان را دارید و هم کلیدتان اجازه‌ی استفاده از آن‌ها را دارد، و فقط مدل‌هایی که با همان API می‌شود با آن‌ها گفتگو کرد (با هدر x-api-key یا anthropic-version پاسخ به شکل Anthropic است). مدل‌های بردارسازی در این فهرست نمی‌آیند؛ آن‌ها را با GET /v1/models?capability=embedding بخوانید. قیمت هر مدل به تومان، به‌ازای هر ۱ میلیون توکن، در صفحه‌ی «شارژ اعتبار» است.

گفتگو: سبک OpenAI

POST /v1/chat/completions همان قالب OpenAI را می‌پذیرد، با پاسخ معمولی یا stream: true. ابزارها (tools)، تصویر و بقیه‌ی فیلدهای مدل بی‌تغییر به ارائه‌دهنده می‌رسند و پاسخ با شناسه‌ی مدلِ ما برمی‌گردد. برای دیدن مصرف در پایان stream، stream_options.include_usage را روشن کنید.

from openai import OpenAI

client = OpenAI(base_url="https://api.tokenprovider.ir/v1", api_key="YOUR_API_KEY")
stream = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "یک داستان کوتاه بگو"}],
    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="")

گفتگو: سبک Anthropic و Claude Code

POST /v1/messages (و POST /v1/messages/count_tokens که رایگان است) قالب Anthropic را می‌پذیرد؛ max_tokens اجباری است و هدرهای anthropic-version و anthropic-beta به ارائه‌دهنده می‌رسند. فقط مدل‌هایی که ارائه‌دهنده‌شان API بومی Anthropic دارد از این مسیر سرو می‌شوند. برای Claude Code:

curl https://api.tokenprovider.ir/v1/messages \
  -H "x-api-key: $TOKENPROVIDER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 200,
    "messages": [{"role": "user", "content": "سلام!"}]
  }'

export ANTHROPIC_BASE_URL="(the base URL above, without /v1)" · export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"

Embeddings

POST /v1/embeddings با قالب OpenAI: input یک متن یا فهرستی از متن‌ها (حداکثر ۲۵۶ متن در هر درخواست) و در صورت پشتیبانی مدل، dimensions و encoding_format. هزینه فقط بر اساس توکن‌های ورودی است. برای پاسخ‌های بزرگ، encoding_format: "base64" حجم را حدود یک‌چهارم می‌کند.

curl https://api.tokenprovider.ir/v1/embeddings \
  -H "Authorization: Bearer $TOKENPROVIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "EMBEDDING_MODEL_ID", "input": ["سلام دنیا", "hello world"]}'

هزینه و صورتحساب

• اعتبار هر گروه مدل جدا شارژ می‌شود و فقط برای مدل‌های همان گروه خرج می‌شود.
• هزینه‌ی هر درخواست دقیقاً از مصرف واقعی ارائه‌دهنده (توکن ورودی و خروجی) و قیمت اعلام‌شده حساب می‌شود، نه بیشتر. اول بیشترین مقداری که ممکن است خرج شود نگه داشته می‌شود و پس از پایان، باقی‌مانده برمی‌گردد.
• درخواستی که به خطای ارائه‌دهنده بخورد و پاسخی نگیرد هزینه‌ای ندارد.
• مصرف هر کلید و هر مدل را در «مصرف» می‌بینید.

محدودیت‌ها

• برای هر کلید سقف سرعت وجود دارد (به‌طور پیش‌فرض ۶۰۰ درخواست و ۲ میلیون توکن در دقیقه و ۱۶ درخواست هم‌زمان؛ هنگام ساخت کلید می‌توانید کمترش کنید) و برای کل حساب ۳۲ درخواست هم‌زمان. هنگام عبور، پاسخ ۴۲۹ با هدر Retry-After می‌آید.
• بدنه‌ی درخواست حداکثر ۸ مگابایت است.
• پاسخ‌های بسیار بلند را با stream: true بگیرید.
• در embeddings حداکثر ۲۵۶ متن و پاسخی تا ۸ مگابایت؛ متنی که چند برابر حدّ مدل است رد می‌شود.

خطاها

خطا همیشه یک JSON است. در مسیرهای OpenAI به شکل زیر، و در /v1/messages به قالب Anthropic ({"type":"error","error":{"type","message"}}):

{
  "error": {
    "message": "Not enough credits for 'MODEL_ID'. Top up your balance to continue.",
    "type": "billing_error",
    "code": "insufficient_credits"
  }
}

هنوز چیزی کم است؟

وضعیت لحظه‌ای مدل‌ها در وضعیت سرویس است و راه‌های ارتباط با پشتیبانی پایین صفحه‌ی قوانین آمده است.