آموزش API دیپ‌سیک V3.2: از کلید تا اولین پاسخ

برای اولین پاسخ از API دیپ‌سیک چهار قدم کافی است: حساب کسب‌وکار، شارژ، کلید و یک درخواست. این راهنما همین چهار قدم را با مدل DeepSeek V3.2 نشان می‌دهد، با پرداخت ریالی و بدون واسطهٔ دیگر. معرفی دیپ‌سیک در منابع فارسی زیاد است؛ آموزش اتصال کمتر دیده می‌شود.

قدم اول: حساب و موجودی

در پنل کسب‌وکار حساب بسازید و موجودی کیف پول را شارژ کنید. هزینهٔ هر فراخوان از همین موجودی کسر می‌شود و مبلغ دقیقش در پاسخ می‌آید.

قدم دوم: کلید API

از بخش کلیدها یک کلید بسازید. کلیدها با melli_live_ شروع می‌شوند. کلید را فقط یک بار می‌بینید؛ همان لحظه در متغیر محیطی سرور خودتان بگذارید و در مخزن کد یا پیام چت قرار ندهید.

export MELLIAPI_API_KEY="کلید-شما"

قدم سوم: اولین درخواست

curl https://melliapi.net/api/v1/ai/chat/completions/ \
  -H "Authorization: Bearer $MELLIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-deepseek-v3.2",
    "max_tokens": 200,
    "messages": [
      {"role": "user", "content": "پایتخت ایران کجاست؟"}
    ]
  }'

هدر X-API-Key هم به‌جای Authorization پذیرفته می‌شود.

قدم چهارم: خواندن پاسخ

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

• content متن جواب است.
• billing.amountRial مبلغی است که واقعاً کسر شد.
• requestId را نگه دارید. برای پیگیری یک فراخوان در پشتیبانی تنها همین را داریم، چون متن پیام‌ها را ذخیره نمی‌کنیم.

همین کار در Python

import os, requests

r = requests.post(
    "https://melliapi.net/api/v1/ai/chat/completions/",
    headers={"Authorization": "Bearer " + os.environ["MELLIAPI_API_KEY"]},
    json={
        "model": "deepseek-deepseek-v3.2",
        "max_tokens": 200,
        "messages": [{"role": "user", "content": "پایتخت ایران کجاست؟"}],
    },
    timeout=60,
)
data = r.json()
print(data["content"] if data["ok"] else data["error"]["code"])

وقتی خطا گرفتید

پاسخ ناموفق ok: false و یک error.code دارد. سه تا از رایج‌ترین‌ها: unauthorized یعنی کلید اشتباه است، insufficient_funds یعنی موجودی کم است، و rate_limited یعنی از ۶۰ فراخوان در دقیقه گذشته‌اید و باید به هدر Retry-After نگاه کنید. فهرست کامل در بخش خطاهای هوش مصنوعی هست.

پیش از رفتن به محیط واقعی

اولین درخواست که جواب داد، کار تمام نیست. سه چیز را پیش از استقرار در برنامهٔ خودتان بگذارید:

• مهلت اتصال: برای گفت‌وگوی کوتاه یک دقیقه کافی است. اگر max_tokens را بزرگ می‌گذارید یا پاسخ جریانی ندارید، مهلت را بلندتر بگیرید. مهلتی که وسط تولید قطع شود، هزینه را می‌گیرد ولی جوابی نمی‌دهد.
• تلاش دوباره، فقط برای خطای موقت: برای temporarily_unavailable و rate_limited چند ثانیه صبر کنید و دوباره بفرستید. برای unauthorized یا insufficient_funds تلاش دوباره فایده ندارد و فقط خطا را تکرار می‌کند.
• ذخیرهٔ requestId: کنار هر پاسخ در لاگ خودتان نگه دارید تا اگر مشتری از جوابی شکایت کرد، پیگیری ممکن باشد.

نکتهٔ هزینه: max_tokens

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

آنچه این راهنما نمی‌گوید

• قیمت را نمی‌نویسد. قیمت زنده در صفحهٔ مدل هست.
• دادهٔ حساس را حفظ نمی‌کند. هر چیزی که در پیام بفرستید به ارائه‌دهندهٔ مدل می‌رسد. کد ملی، شمارهٔ کارت و دادهٔ شخصیِ غیرلازم را پیش از ارسال حذف کنید.