مستندات API هوش مصنوعی

کلید را در هدر Authorization بفرستید. هدر x-api-key هم پذیرفته می‌شود.

Authorization: Bearer ehr_live_…

⚠️ کلید فقط سمت سرور نگهداری شود. کلیدی که در جاوااسکریپت مرورگر یا اپلیکیشن موبایل بنشیند، در دسترس هر کسی است که ابزار توسعه‌دهندهٔ مرورگر را باز کند.

اگر IP سرورتان ثابت است، هنگام ساخت کلید فهرست IP مجاز را پر کنید؛ آن‌وقت کلیدِ نشت‌کرده از جای دیگر کار نمی‌کند.

POST https://ehrazino.com/api/v1/ai/chat/completions/

{
  "model": "gemini-flash",
  "messages": [
    { "role": "system", "content": "پاسخ‌ها را کوتاه و فارسی بده." },
    { "role": "user", "content": "پایتخت ایران کجاست؟" }
  ],
  "max_tokens": 200,
  "temperature": 0.3
}

پاسخ موفق

{
  "ok": true,
  "requestId": "req_7f3c…",
  "model": "gemini-flash",
  "content": "تهران.",
  "usage": { "promptTokens": 42, "completionTokens": 3 },
  "finishReason": "stop",
  "billing": { "amountRial": 710, "balanceRial": 48912340 }
}

🔴 billing.amountRial مبلغی است که واقعاً کسر شد و نه سقفی که پیش از تماس قفل شده بود. تفاوت این دو همان لحظه به موجودی برمی‌گردد.

requestId را نگه دارید. تنها چیزی است که برای پیگیری یک فراخوان در پشتیبانی به کار می‌آید — چون متن پیام‌ها را نگه نمی‌داریم.

با فرستادن "stream": true، پاسخ به‌صورت text/event-stream تکه‌تکه می‌آید. هر تکه یک خط data: است.

data: {"requestId":"req_7f3c…","delta":"ته"}

data: {"requestId":"req_7f3c…","delta":"ران."}

data: {"requestId":"req_7f3c…","done":true,"usage":{"promptTokens":42,"completionTokens":3},"billing":{"amountRial":710}}

data: [DONE]

⚠️ صورتحساب در تکهٔ پایانی می‌آید، نه در ابتدا — چون هزینه تا پایان تولید معلوم نیست. اگر ارتباط را وسط کار قطع کنید، بابت همان مقداری که تولید شده هزینه کسر می‌شود؛ مدل تا آن لحظه کار کرده است.

اگر پیش از شروع جریان خطایی رخ دهد — کلید نامعتبر، موجودی ناکافی، مدل خاموش — پاسخ یک JSON معمولی با کد وضعیت مناسب است و نه جریان. پس همیشه content-type را بررسی کنید.

POST https://ehrazino.com/api/v1/ai/images/

{
  "model": "nano-banana",
  "input": {
    "prompt": "یک فنجان قهوه روی میز چوبی، نور طبیعی"
  }
}

🔴 محتوای input دست‌نخورده به مدل می‌رود و ما اعتبارسنجی‌اش نمی‌کنیم. هر مدل ورودی‌های خودش را دارد (prompt، image، aspect_ratio…). اگر مدل ورودی را رد کند، invalid_input برمی‌گردد و هزینه‌ای ندارد.

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

پاسخ موفق

{
  "ok": true,
  "requestId": "req_9b1d…",
  "model": "nano-banana",
  "output": ["https://…/output.png"],
  "billing": { "amountRial": 531300, "balanceRial": 48381040 }
}

output همان چیزی است که مدل برگردانده و شکلش به مدل بستگی دارد — معمولاً فهرستی از نشانی تصویر. مهلت این مسیر بلندتر از گفت‌وگوست؛ timeout سمت خودتان را دست‌کم ۱۲۰ ثانیه بگذارید.

هر پاسخ ناموفق همین شکل را دارد و کد وضعیت HTTP هم با آن می‌خواند:

{
  "ok": false,
  "requestId": "req_7f3c…",
  "error": { "code": "insufficient_funds", "message": "…" },
  "billing": { "amountRial": 0, "balanceRial": 120000 }
}

⚠️ 429 هدر Retry-After دارد؛ به‌جای تلاش فوری، همان اندازه صبر کنید.

• پیش از تماس با مدل، سقف هزینه از موجودی قفل می‌شود. پس از پاسخ، مبلغ واقعی کسر و باقی همان لحظه آزاد می‌شود.
• سقف خروجی را با max_tokens خودتان تعیین می‌کنید. اگر نفرستید، سقف پیش‌فرض همان مدل اعمال می‌شود.
• ورودی نامعتبر، در دسترس نبودن مدل و عبور از سقف نرخ هزینه‌ای ندارند.
• اگر ارائه‌دهنده شمار توکن را گزارش نکند، فراخوان رایگان حساب می‌شود. ضررش با ماست، نه شما.

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

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

curl

curl -X POST 'https://ehrazino.com/api/v1/ai/chat/completions/' \
  -H 'Authorization: Bearer ehr_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"model":"gemini-flash","messages":[{"role":"user","content":"سلام"}],"max_tokens":200}'

Node.js

const response = await fetch('https://ehrazino.com/api/v1/ai/chat/completions/', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EHRAZINO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gemini-flash',
    messages: [{ role: 'user', content: prompt }],
    max_tokens: 200,
  }),
});

const body = await response.json();
if (body.ok) {
  console.log(body.content, body.billing.amountRial);
}

Python

import os, requests

response = requests.post(
    "https://ehrazino.com/api/v1/ai/chat/completions/",
    headers={"Authorization": f"Bearer {os.environ['EHRAZINO_API_KEY']}"},
    json={
        "model": "gemini-flash",
        "messages": [{"role": "user", "content": prompt}],
        "max_tokens": 200,
    },
    timeout=120,
)
body = response.json()
if body.get("ok"):
    print(body["content"], body["billing"]["amountRial"])

PHP / وردپرس

$response = wp_remote_post( 'https://ehrazino.com/api/v1/ai/chat/completions/', array(
    'timeout' => 120,
    'headers' => array(
        'Authorization' => 'Bearer ' . EHRAZINO_API_KEY,
        'Content-Type'  => 'application/json',
    ),
    'body' => wp_json_encode( array(
        'model'      => 'gemini-flash',
        'messages'   => array( array( 'role' => 'user', 'content' => $prompt ) ),
        'max_tokens' => 200,
    ) ),
) );

if ( is_wp_error( $response ) ) {
    return; // شبکه قطع بود — دوباره تلاش کنید.
}

$body = json_decode( wp_remote_retrieve_body( $response ), true );
if ( ! empty( $body['ok'] ) ) {
    // $body['content'] پاسخ مدل است.
}

⚠️ مهلت (timeout) را دست‌کم ۱۲۰ ثانیه بگذارید. پاسخ‌های بلند زمان می‌برند و مهلت کوتاه یعنی شما پاسخ را نمی‌بینید در حالی که صورتحسابش صادر شده.

متن پیام‌ها و پاسخ مدل ذخیره نمی‌شود. از هر فراخوان فقط نام مدل، وضعیت، شمار توکن، مبلغ و زمان ثبت می‌شود — همان چیزی که در بخش هوش مصنوعی پنل می‌بینید.