پرش به مطلب اصلی

شروع سریع

در این راهنما از صفر تا اولین پاسخ مدل پیش می‌رویم. کل مسیر کمتر از پنج دقیقه طول می‌کشد.

پیش‌نیازها​

شارژ کیف پول

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

گام ۱ — ساخت کلید API​

۱. وارد کنسول کاربری شوید. ۲. از منوی کناری به هوش مصنوعی → کلیدهای API بروید. ۳. روی دکمه + ایجاد کلید جدید کلیک کنید. ۴. یک نام کلید انتخاب کنید — نامی که بعداً کاربرد کلید را یادآوری کند، مثلاً پروژه فروشگاه یا تست محلی. ۵. روی ایجاد کلید کلیک کنید.

کلید فقط یک بار نمایش داده می‌شود

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

کلید ساخته‌شده چیزی شبیه این است:

sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

می‌توانید هنگام ساخت کلید، محدودیت بودجه، محدودیت نرخ و تاریخ انقضا هم تعیین کنید. جزئیات در صفحه کلیدهای API.

گام ۲ — ذخیره کلید در متغیر محیطی​

کلید را مستقیم داخل کد ننویسید. به‌جای آن در یک متغیر محیطی نگه دارید:

export NOVIN_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

برای ویندوز (PowerShell):

$env:NOVIN_API_KEY = "sk-xxxxxxxxxxxxxxxxxxxxxxxx"

گام ۳ — اولین درخواست​

با cURL​

curl https://iapi.novin.cloud/v1/chat/completions \
  -H "Authorization: Bearer $NOVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {"role": "user", "content": "در یک جمله بگو هوش مصنوعی چیست؟"}
    ]
  }'

پاسخ چیزی شبیه این خواهد بود:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "هوش مصنوعی شاخه‌ای از علوم کامپیوتر است که..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 42,
    "total_tokens": 60
  }
}

بخش usage نشان می‌دهد چند توکن مصرف شده — همین عدد مبنای محاسبه هزینه است.

با Python​

ابتدا کتابخانه رسمی OpenAI را نصب کنید:

pip install openai

سپس:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NOVIN_API_KEY"],
    base_url="https://iapi.novin.cloud/v1",
)

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[
        {"role": "user", "content": "در یک جمله بگو هوش مصنوعی چیست؟"}
    ],
)

print(response.choices[0].message.content)

با Node.js​

npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NOVIN_API_KEY,
  baseURL: "https://iapi.novin.cloud/v1",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [
    { role: "user", content: "در یک جمله بگو هوش مصنوعی چیست؟" },
  ],
});

console.log(response.choices[0].message.content);

گام ۴ — دریافت پاسخ به‌صورت استریم​

برای اینکه پاسخ کلمه‌به‌کلمه و بدون انتظار نمایش داده شود، کافی است stream: true را اضافه کنید:

stream = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "یک داستان کوتاه بنویس"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

گام ۵ — گفتگوی چندمرحله‌ای​

مدل‌ها حافظه ندارند. برای ادامه یک گفتگو، باید تمام پیام‌های قبلی را در هر درخواست بفرستید:

messages = [
    {"role": "system", "content": "تو یک دستیار فارسی‌زبان هستی."},
    {"role": "user", "content": "پایتخت ایران کجاست؟"},
]

response = client.chat.completions.create(
    model="openai/gpt-4o", messages=messages
)
answer = response.choices[0].message.content

# پاسخ مدل را به تاریخچه اضافه کنید
messages.append({"role": "assistant", "content": answer})
# حالا سوال بعدی
messages.append({"role": "user", "content": "جمعیتش چقدر است؟"})

response = client.chat.completions.create(
    model="openai/gpt-4o", messages=messages
)
print(response.choices[0].message.content)
هزینه گفتگوی طولانی

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

نقش‌های پیام​

نقشکاربرد
systemتعیین رفتار و شخصیت مدل — در ابتدای گفتگو
userپیام کاربر
assistantپاسخ قبلی مدل — برای حفظ تاریخچه

خطاهای رایج​

کدمعنیراه‌حل
401کلید نامعتبر استکلید را بررسی کنید؛ مطمئن شوید حذف یا منقضی نشده
402موجودی کیف پول کافی نیستکیف پول را شارژ کنید
429عبور از محدودیت نرخچند لحظه صبر کنید یا محدودیت کلید را افزایش دهید
404مدل یافت نشدشناسه مدل را با فهرست مدل‌ها مطابقت دهید

گام بعدی​