استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL
چطور پروژه‌ای را که با کتابخانه‌ی OpenAI نوشته شده، فقط با تغییر آدرس پایه و کلید به 1ai وصل کنید؛ با نمونه کد Python، Node.js و cURL، استریم، فهرست مدل‌ها و مدیریت خطا.
رابط برنامه‌نویسی (API) در 1ai با قالب OpenAI سازگار است. یعنی اگر کدی دارید که با کتابخانه‌ی رسمی OpenAI (یا هر ابزاری که از آن پشتیبانی می‌کند) کار می‌کند، کافی است آدرس پایه و کلید را عوض کنید تا به مدل‌های خانواده‌های مختلف، با پرداخت ریالی و از یک کیف اعتبار، دسترسی داشته باشید.
آنچه لازم دارید
- آدرس پایه:
https://1ai.ir/v1 - کلید API: از پنل، بخش «توسعه‌دهندگان ← کلیدها» بسازید. کلیدها با
sk-1ai-شروع می‌شوند و فقط یک‌بار نمایش داده می‌شوند. - شناسه‌ی مدل: در صفحه‌ی هر مدل در فهرست مدل‌ها نوشته شده، یا از
GET /v1/modelsبگیرید. شناسه‌ها به شکلسازنده/مدلهستند. در مثال‌های این مقاله ازopenai/gpt-5.4-miniاستفاده شده است؛ آن را با مدل دلخواه خود عوض کنید.
کلید را در کد ننویسید؛ آن را در متغیر محیطی نگه دارید:
export ONEAI_API_KEY="sk-1ai-..."کلید را فقط در سمت سرور به کار ببرید. کلیدی که در کد فرانت‌اند، اپلیکیشن موبایل یا مخزن عمومی قرار بگیرد، عملاً افشا شده است.
اولین درخواست
نمونه با cURL
curl https://1ai.ir/v1/chat/completions \
-H "Authorization: Bearer $ONEAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.4-mini",
"messages": [
{"role": "system", "content": "You are a helpful assistant. Answer in Persian."},
{"role": "user", "content": "Explain what an API is in two sentences."}
]
}'نمونه با Python
import os
from openai import OpenAI
client = OpenAI(
base_url="https://1ai.ir/v1",
api_key=os.environ["ONEAI_API_KEY"],
)
reply = client.chat.completions.create(
model="openai/gpt-5.4-mini",
messages=[
{"role": "system", "content": "You are a helpful assistant. Answer in Persian."},
{"role": "user", "content": "Explain what an API is in two sentences."},
],
)
print(reply.choices[0].message.content)نمونه با Node.js
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://1ai.ir/v1",
apiKey: process.env.ONEAI_API_KEY,
});
const reply = await client.chat.completions.create({
model: "openai/gpt-5.4-mini",
messages: [
{ role: "system", content: "You are a helpful assistant. Answer in Persian." },
{ role: "user", content: "Explain what an API is in two sentences." },
],
});
console.log(reply.choices[0].message.content);اگر از ابزار یا فریم‌ورکی استفاده می‌کنید که «OpenAI-compatible» را پشتیبانی می‌کند، معمولاً همان دو تنظیم آدرس پایه و کلید کافی است.
پاسخ استریم
برای نمایش تدریجی پاسخ (مثل رابط گفتگو)، stream را روشن کنید. با stream_options.include_usage آخرین بخش پاسخ، مصرف توکن و اعتبار را هم برمی‌گرداند:
stream = client.chat.completions.create(
model="openai/gpt-5.4-mini",
messages=[{"role": "user", "content": "Write a short poem about the sea."}],
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="", flush=True)
if chunk.usage:
print("\n", chunk.usage)فهرست مدل‌ها
curl https://1ai.ir/v1/models -H "Authorization: Bearer $ONEAI_API_KEY"پاسخ فقط مدل‌هایی را نشان می‌دهد که این کلید اجازه‌ی استفاده از آن‌ها را دارد، همراه با قابلیت‌ها، طول پنجره‌ی متنی و قیمت هر واحد به اعتبار.
چه endpointهایی پشتیبانی می‌شوند؟
| مسیر | کاربرد |
|---|---|
POST /v1/chat/completions | گفتگو، استریم، فراخوانی ابزار (tools)، خروجی JSON |
POST /v1/embeddings | بردار متن برای جست‌وجوی معنایی و RAG |
POST /v1/images/generations | ساخت تصویر |
POST /v1/audio/speech | تبدیل متن به گفتار |
POST /v1/audio/transcriptions | تبدیل گفتار به متن |
GET /v1/models | فهرست مدل‌های در دسترس |
دسترسی به هر قابلیت به مدل‌هایی بستگی دارد که در آن لحظه فعال‌اند.
هزینه‌ی هر درخواست
درخواست‌های API از همان کیف اعتبار حساب شما مصرف می‌کنند و قیمت مدل‌ها همان قیمت پنل است. پیش از اجرای درخواست، اعتبار لازم بر اساس تخمین رزرو و بعد از پاسخ، فقط مصرف واقعی کسر می‌شود.
- در پاسخ‌های عادی، هدر
x-1ai-creditsاعتبار مصرف‌شده را نشان می‌دهد. - در استریم، با
include_usageمقدارusage.creditsدر آخرین بخش می‌آید. - نمودار مصرف و گزارش تک‌تک درخواست‌ها (وضعیت، توکن‌ها، تأخیر و هزینه) در بخش «توسعه‌دهندگان» پنل است.
مدیریت خطا
خطاها در همان قالب OpenAI برمی‌گردند ({"error": {"message", "type", "code"}}). مهم‌ترین‌ها:
| کد HTTP | معنا | چه کنیم |
|---|---|---|
| 401 | کلید نامعتبر، باطل یا منقضی | کلید را بررسی یا کلید تازه بسازید |
| 402 | اعتبار کافی نیست یا سقف ماهانه‌ی کلید پر شده | اعتبار بخرید یا سقف را بالا ببرید |
| 403 | این مدل برای کلید یا حساب شما مجاز نیست | فهرست مدل‌های مجاز کلید را بررسی کنید |
| 429 | محدودیت نرخ | بر اساس هدر retry-after صبر کنید و دوباره بفرستید |
| 5xx | خطای موقت ارائه‌دهنده | با تأخیر افزایشی دوباره تلاش کنید |
کتابخانه‌ی رسمی OpenAI به‌صورت پیش‌فرض خطاهای 429 و 5xx را چند بار دوباره امتحان می‌کند. هدرهای x-ratelimit-* هم وضعیت محدودیت نرخ را نشان می‌دهند.
پایداری
پشت هر مدل ممکن است بیش از یک ارائه‌دهنده باشد. اگر یکی پیش از شروع پاسخ خطا بدهد، درخواست به‌صورت خودکار به مسیر دیگری می‌رود؛ بنابراین بیشتر قطعی‌های موقت به برنامه‌ی شما نمی‌رسد.
گام بعدی
برای محدود کردن مدل‌ها، سقف هزینه و محدودیت نرخ هر کلید، مقاله‌ی کلید API و کنترل هزینه را بخوانید. در پنل هم یک محیط آزمایش هست که می‌توانید پیش از نوشتن کد، مدل‌ها را امتحان کنید.
پرسش‌های کوتاه
آیا کلید OpenAI خودم را لازم دارم؟ خیر. فقط کلید 1ai لازم است و هزینه از اعتبار حساب 1ai شما کم می‌شود.
می‌توانم از مدل‌های غیر OpenAI هم با همین کتابخانه استفاده کنم؟
بله. مدل‌های خانواده‌های دیگر هم با همان قالب chat/completions در دسترس‌اند؛ فقط شناسه‌ی model را عوض کنید.
