docs / api-reference

مرجع API

همه‌چیز برای اتصال برنامه شما به مدل‌های آنی‌گپ: احراز هویت، گفتگو، استریم، تصویر، صدا و خطاها — دقیقا همان‌طور که سرویس واقعا رفتار می‌کند.

01

معرفی

آنی‌گپ یک اندپوینت سازگار ارائه می‌دهد: اگر کلاینت یا SDK شما با قرارداد رایج chat/completions کار می‌کند، کافی است آدرس پایه را عوض کنید — بقیه کد شما دست‌نخورده می‌ماند.

base url
https://anygap.ir/v1

اندپوینت‌های موجود:

متد و مسیراحراز هویتکاربرد
GET /v1/modelsعمومیلیست مدل‌های فعال
POST /v1/chat/completionsکلید APIگفتگو (عادی و استریم)
POST /v1/images/generationsکلید APIتولید تصویر
POST /v1/audio/transcriptionsکلید APIرونویسی صدا
02

احراز هویت

از داشبورد ← کلیدهای API یک کلید جدید بسازید. کلیدها با پیشوند agp- شروع می‌شوند (کلیدهای قدیمی gpt- همچنان معتبرند) و مقدار کامل آن‌ها فقط یک بار، هنگام ساخت نمایش داده می‌شود — بعدا فقط نسخه ماسک‌شده را می‌بینید.

کلید را در هدر Authorization هر درخواست بفرستید:

http header
Authorization: Bearer agp-1f87c3a9e4b2d6f0c5a8e1b4d7f0a3c6e9b2d5f8a1c4e7b0d3f6a9c2e5b8d1f4
نکات امنیتی
  • کلید را هرگز در کد فرانت‌اند، مخزن گیت یا سمت کلاینت قرار ندهید — فقط از سرور خودتان فراخوانی کنید.
  • کلید را در متغیر محیطی نگه دارید (مثلا ANYGAP_API_KEY).
  • اگر کلیدی لو رفت، از داشبورد آن را غیرفعال یا برای همیشه حذف کنید و یک کلید جدید بسازید. می‌توانید برای هر برنامه یک کلید جدا داشته باشید.
03

تکمیل گفتگو

POST /v1/chat/completions — قلب API. یک مدل و آرایه‌ای از پیام‌ها می‌فرستید و پاسخ مدل را می‌گیرید. فیلدهای model و messages الزامی‌اند؛ بقیه پارامترها بدون تغییر به مدل پاس داده می‌شوند.

فیلدنوعالزامیتوضیح
modelstringبلهاسلاگ مدل — مثل gpt-oss-120b. لیست کامل در GET /v1/models.
messagesarrayبلهآرایه پیام‌ها با role (system | user | assistant | tool) و content. برای مدل‌های بینایی، content می‌تواند آرایه‌ای از بخش‌های text و image_url باشد.
streambooleanخیرپیش‌فرض false. با true پاسخ به صورت SSE استریم می‌شود.
temperaturenumberخیرمیزان خلاقیت پاسخ. مستقیم به مدل ارسال می‌شود.
max_tokensintegerخیرحداکثر توکن خروجی. مستقیم به مدل ارسال می‌شود.
top_p, stop, ...خیرسایر پارامترهای استاندارد نمونه‌برداری بدون تغییر به مدل پاس داده می‌شوند.

درخواست بدون استریم:

terminal — bash
curl https://anygap.ir/v1/chat/completions \
  -H "Authorization: Bearer $ANYGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-oss-120b",
    "messages": [
      {"role": "user", "content": "سلام! خودت را معرفی کن."}
    ]
  }'

پاسخ:

response — 200 OK
{
  "id": "chatcmpl-9f3c...",
  "object": "chat.completion",
  "created": 1718182800,
  "model": "gpt-oss-120b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "سلام! من دستیار هوش مصنوعی آنی‌گپ هستم..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 38,
    "total_tokens": 50
  }
}

استریم (SSE)

با "stream": true پاسخ به‌صورت Server-Sent Events با هدر Content-Type: text/event-stream برمی‌گردد. هر رویداد یک خط data: با یک قطعه JSON است که متن تازه در choices[0].delta.content قرار دارد. پایان استریم با data: [DONE] اعلام می‌شود.

terminal — bash (-N keeps the stream open)
curl -N https://anygap.ir/v1/chat/completions \
  -H "Authorization: Bearer $ANYGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-oss-20b",
    "messages": [{"role": "user", "content": "Count to three."}],
    "stream": true
  }'
event stream — text/event-stream
data: {"id":"chatcmpl-9f3c...","object":"chat.completion.chunk","created":1718182800,"model":"gpt-oss-20b","choices":[{"index":0,"delta":{"role":"assistant","content":"One"},"finish_reason":null}]}

data: {"id":"chatcmpl-9f3c...","object":"chat.completion.chunk","created":1718182800,"model":"gpt-oss-20b","choices":[{"index":0,"delta":{"content":", two"},"finish_reason":null}]}

data: {"id":"chatcmpl-9f3c...","object":"chat.completion.chunk","created":1718182800,"model":"gpt-oss-20b","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
04

مدل‌ها

هر مدل با یک اسلاگ شناخته می‌شود که در فیلد model می‌فرستید. لیست زنده مدل‌های API را از GET /v1/models (بدون نیاز به کلید) بگیرید. کاتالوگ API با مدل‌های اپلیکیشن چت متفاوت است — این‌جا مدل‌ها با نام واقعی‌شان ارائه می‌شوند و همگی با یک قیمت ثابت برای هر درخواست در دسترس‌اند.

terminal — bash
curl https://anygap.ir/v1/models
response — 200 OK
{
  "object": "list",
  "data": [
    {
      "id": "gpt-oss-120b",
      "object": "model",
      "created": 1714521600,
      "owned_by": "anygap",
      "permission": [],
      "root": "gpt-oss-120b",
      "parent": null
    }
  ]
}

کاتالوگ فعلی API (همین لیست را اندپوینت بالا زنده برمی‌گرداند):

اسلاگنامدستهکانتکستقیمت هر درخواست
gpt-oss-120bGPT-OSS 120Bchat131K۱٬۰۰۰ تومان
gpt-oss-20bGPT-OSS 20Bchat131K۱٬۰۰۰ تومان
llama-3.3-70b-instructLlama 3.3 70B Instructchat131K۱٬۰۰۰ تومان
gemma-4-26bGemma 4 26Bchat262K۱٬۰۰۰ تومان
gemma-4-31bGemma 4 31Bchat262K۱٬۰۰۰ تومان
qwen3-coderQwen3 Coderchat1M۱٬۰۰۰ تومان
qwen3-next-80bQwen3 Next 80Bchat262K۱٬۰۰۰ تومان
nemotron-3-super-120bNemotron 3 Super 120Bchat1M۱٬۰۰۰ تومان
nemotron-3-ultra-550bNemotron 3 Ultra 550Bchat1M۱٬۰۰۰ تومان
gemini-3-pro-imageGemini 3 Pro Imageimage۱٬۰۰۰ تومان
gemini-3.1-flash-imageGemini 3.1 Flash Imageimage۱٬۰۰۰ تومان
05

تولید تصویر

POST /v1/images/generations — فیلدهای الزامی model (یک مدل با دسته image، مثل gemini-3-pro-image یا gemini-3.1-flash-image) و prompt. فیلد n تعداد تصویر است (۱ تا ۸، پیش‌فرض ۱) و پارامترهای اختیاری مثل size، quality و response_format به مدل پاس داده می‌شوند. ارسال اسلاگ غیرتصویری خطای 400 برمی‌گرداند.

terminal — bash
curl https://anygap.ir/v1/images/generations \
  -H "Authorization: Bearer $ANYGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "غروب آفتاب روی دریا، سبک نقاشی",
    "n": 1
  }'
06

رونویسی صدا

POST /v1/audio/transcriptions — برخلاف بقیه اندپوینت‌ها، بدنه باید multipart/form-data باشد: بخش file (فایل صوتی، حداکثر حدود ۲۵ مگابایت) و بخش متنی model (اسلاگ یک مدل با دسته audio). فیلدهای اختیاری مثل language، prompt، response_format و temperature هم پاس داده می‌شوند. در دسترس بودن مدل صوتی به لیست زنده مدل‌ها بستگی دارد — قبل از استفاده، GET /v1/models را بررسی کنید.

terminal — bash
curl https://anygap.ir/v1/audio/transcriptions \
  -H "Authorization: Bearer $ANYGAP_API_KEY" \
  -F file=@meeting.mp3 \
  -F model=AUDIO_MODEL_SLUG
07

خطاها

همه خطاها با یک شکل JSON واحد برمی‌گردند:

error body
{
  "error": {
    "message": "Invalid API key",
    "type": "AuthenticationError",
    "code": 401
  }
}
کدtypeچه زمانی رخ می‌دهد
400ValidationErrorبدنه ناقص یا نامعتبر — مثلا نبود model یا messages، یا استفاده از مدل غیرتصویری در /images/generations.
401AuthenticationErrorهدر Authorization غایب یا بدفرمت، کلید نامعتبر یا غیرفعال، یا حساب کاربری مسدود.
402InsufficientBalanceErrorموجودی کیف پول کافی نیست.
404NotFoundErrorاسلاگ مدل ناشناخته/غیرفعال است یا ارائه‌دهنده آن موقتا در دسترس نیست.
5xxInternalErrorخطای غیرمنتظره در گیت‌وی یا خطای سرویس بالادستی.

در تولید تصویر و رونویسی صدا، اگر سرویس بالادستی خطا بدهد، همان کد وضعیت و بدنه خطای بالادستی عینا به شما برگردانده می‌شود.

08

نمونه کد

هر سه نمونه با همان کلیدی که در داشبورد ساختید، قابل اجرا هستند.

python — requests
import requests

API_KEY = "agp-..."  # از /dashboard/keys

resp = requests.post(
    "https://anygap.ir/v1/chat/completions",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "llama-3.3-70b-instruct",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "یک هایکو درباره دریا بنویس"},
        ],
        "temperature": 0.7,
        "max_tokens": 512,
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])
python — SDK رسمی دلخواه شما + اندپوینت سازگار
# هر SDK رسمی دلخواه — کافی است base_url را به اندپوینت سازگار ما بدهید.
from openai import OpenAI

client = OpenAI(
    base_url="https://anygap.ir/v1",
    api_key="agp-...",  # کلید آنی‌گپ شما
)

stream = client.chat.completions.create(
    model="gemma-4-26b",
    messages=[{"role": "user", "content": "سه ایده برای اسم یک کافه"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
node.js — fetch (streaming)
const res = await fetch("https://anygap.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ANYGAP_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "qwen3-coder",
    messages: [{ role: "user", content: "Explain SSE in one paragraph." }],
    stream: true,
  }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("\n");
  buffer = lines.pop() ?? "";
  for (const line of lines) {
    if (!line.startsWith("data: ") || line === "data: [DONE]") continue;
    const chunk = JSON.parse(line.slice(6));
    process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
  }
}
09

انی‌کد (CLI)

انی‌کد یک عاملِ برنامه‌نویسیِ خط‌فرمان و بدون وابستگی برای آنی‌گپ است — مثل Codex یا Claude Code، اما در ترمینال شما. آن را در هر پروژه‌ای اجرا کنید تا کدتان را بخواند، بنویسد، ویرایش کند (همراه با diff)، جست‌وجو و اجرا کند — همه با اجازه‌ی شما — روی https://anygap.ir/v1. فقط به Node 18+ نیاز دارد و یک ماسکوت کوچک ترمینالی مخصوص خودش هم دارد.

۱ · نصب

با npm به‌صورت سراسری نصب کنید — این کار دستور anycode را روی PATH شما قرار می‌دهد:

terminal — bash
npm i -g @anygap/anycode

یا اگر از سورس کار می‌کنید:

terminal — bash (from source)
cd tools/anycode-cli && npm link

۲ · احراز هویت

از داشبورد ← کلیدهای API یک کلید با پیشوند agp- بسازید، سپس anycode login را اجرا کنید (کلید در ~/.anycode/config.json ذخیره می‌شود). به‌جای آن می‌توانید از متغیرهای محیطی ANYCODE_API_KEY و — در صورت تمایل — ANYCODE_MODEL استفاده کنید.

terminal — bash
# روش تعاملی — کلید را در ~/.anycode/config.json ذخیره می‌کند
anycode login

# یا با متغیرهای محیطی
export ANYCODE_API_KEY="agp-..."
export ANYCODE_MODEL="laguna-m1"

۳ · بررسی نصب

برای اطمینان از نصب درست و دیدن مدل‌های در دسترس:

terminal — bash
anycode --help
anycode models

۴ · REPL عاملی

anycode بدون آرگومان یک REPLِ عاملی باز می‌کند. از او بخواهید چیزی بسازد، درست کند یا اجرا کند و او با ابزارهای واقعی همان کار را انجام می‌دهد — فایل می‌سازد، ویرایش می‌کند (به‌صورت diff)، پروژه را جست‌وجو می‌کند و دستور اجرا می‌کند — به‌جای اینکه فقط کد چاپ کند. دستورها و میان‌برها:

دستور / ورودیکاربرد
/model · /modelsانتخاب مدل فعال با کلیدهای ↑/↓
/modeتغییر حالت تأیید (suggest · auto-edit · full-auto)
/diffنمایش diff گیت در دایرکتوری کاری
/initساخت فایل زمینه‌ی پروژه AGENTS.md
/status · /toolsمدل/حالت/مسیر/تعداد دور · فهرست ابزارها
/clear · /cwd · /help · /exitریست · نمایش مسیر · راهنما · خروج
@pathپیوست محتوای یک فایل به‌عنوان زمینه
!commandاجرای مستقیم یک دستور شل

۵ · حالت‌های تأیید و ابزارها

انی‌کد بدون اجازه‌ی شما فایلی را تغییر نمی‌دهد یا دستوری اجرا نمی‌کند. حالت را هر زمان با /mode عوض کنید (یا با --auto-edit / --full-auto شروع کنید):

حالترفتار
suggestپیش از هر ویرایش و دستور می‌پرسد (پیش‌فرض)
auto-editویرایش‌ها خودکار اعمال می‌شوند، برای دستورها می‌پرسد
full-autoویرایش‌ها و دستورها خودکار اجرا می‌شوند

پشت صحنه، عامل هفت ابزار دارد — read_file، list_dir، search، glob، write_file، edit_file و run_command — همه محدود به دایرکتوری جاری، با یک فهرستِ منعِ داخلی که دستورهای خطرناک را در هر حالت مسدود می‌کند. برای اسکریپت‌نویسی، anycode exec یک کار را غیرتعاملی و در حالت full-auto اجرا می‌کند:

terminal — bash
# یک کار را غیرتعاملی (full-auto) اجرا کن و خارج شو
anycode exec "یک اسکریپت پایتون بساز که سلام چاپ کند، بعد اجرایش کن"

# یا REPL را با یک کار اولیه شروع کن
anycode agent "تست‌ها را اجرا کن و خطاها را درست کن"
قیمت‌گذاری

انی‌کد از همان API استفاده می‌کند: هر درخواست یک هزینه ثابت دارد که از کیف پول شما کسر می‌شود — دقیقا مثل بخش «قیمت و کیف پول».

10

پلی‌گراند

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

POST /v1/chat/completions
11

قیمت و کیف پول

قیمت‌گذاری API ساده است: هر مدل یک قیمت ثابت برای هر درخواست دارد — فارغ از طول پیام یا تعداد توکن. در حال حاضر همه مدل‌ها ۱٬۰۰۰ تومان برای هر درخواست. مبلغ پس از پاسخ موفق از کیف پول شما کسر می‌شود و همه درخواست‌ها در صفحه مصرف ثبت می‌شوند.

مدلقیمت هر درخواست
gpt-oss-120b۱٬۰۰۰ تومان
gpt-oss-20b۱٬۰۰۰ تومان
llama-3.3-70b-instruct۱٬۰۰۰ تومان
gemma-4-26b۱٬۰۰۰ تومان
gemma-4-31b۱٬۰۰۰ تومان
qwen3-coder۱٬۰۰۰ تومان
qwen3-next-80b۱٬۰۰۰ تومان
nemotron-3-super-120b۱٬۰۰۰ تومان
nemotron-3-ultra-550b۱٬۰۰۰ تومان
gemini-3-pro-image۱٬۰۰۰ تومان
gemini-3.1-flash-image۱٬۰۰۰ تومان

اگر موجودی کیف پول کمتر از قیمت درخواستِ مدل انتخابی باشد، گیت‌وی پیش از ارسال درخواست خطای 402 برمی‌گرداند. از کیف پول شارژ کنید. درخواست‌های ناموفق (خطای بالادستی) هزینه‌ای ندارند.

آماده‌اید؟

اولین کلید خود را بسازید و در کمتر از یک دقیقه اولین درخواست را بزنید.

ساخت کلید API
anygap