OpenAI SDK با API فارسی 1ai؛ نمونه کد Python و Node.js
اگر برنامهتان با کتابخانهی رسمی `openai` نوشته شده، برای استفاده از وان ای آی (1ai) فقط آدرس پایه، کلید و شناسهی مدل عوض میشود. همان کلاینت به GPT، Claude، Gemini، DeepSeek و Qwen دسترسی پیدا میکند، هزینه از اعتباری کم میشود که با پرداخت ریالی میخرید و برای هر کلید سقف مصرف دارید. این صفحه از اتصال پایه جلوتر میرود: استریم با گزارش هزینه، فراخوانی ابزار، embeddings، ساخت تصویر، تبدیل متن به گفتار و گفتار به متن، و LangChain.

چرا با 1ai
همان کتابخانهی رسمی
بستههای `openai` برای Python و Node.js بدون تغییر کار میکنند؛ فقط `base_url` یا `baseURL` را عوض کنید.
یک کلاینت، چند سازنده
با عوض کردن `model` بین `anthropic/claude-sonnet-5.5`، `openai/gpt-6.1-sol` و `google/gemini-3.8-flash` جابهجا شوید.
چت، بردار، تصویر و صدا
مسیرهای chat/completions، embeddings، images/generations، audio/speech و audio/transcriptions همه با همان کلید کار میکنند.
هزینهی هر درخواست در پاسخ
پاسخهای عادی سرآیند `x-1ai-credits` دارند و در استریم، آخرین قطعهی usage مقدار `credits` را میگوید. اعتبار را با پرداخت ریالی میخرید.
سقف مصرف برای هر کلید
برای هر محیط، مثل توسعه و تولید، کلید جدا با سقف ماهانه، مدلهای مجاز و سقف درخواست در دقیقه بسازید.
در چند قدم
- ۱
کتابخانه را نصب کنید
در Python `pip install openai` و در Node.js `npm install openai` را اجرا کنید.
- ۲
کلید را در متغیر محیطی بگذارید
کلید `sk-1ai-…` را از بخش توسعهدهندگان ← کلیدها بسازید و در `ONEAI_API_KEY` نگه دارید، نه در کد.
- ۳
کلاینت را با آدرس 1ai بسازید
آدرس پایه را `https://1ai.ir/v1` بگذارید و شناسهی مدل را با پیشوند سازنده بنویسید.
- ۴
از Chat Completions استفاده کنید
متن را با `chat.completions.create` بگیرید. مسیر `responses.create` در 1ai وجود ندارد.
مدلهای چت دارای فراخوانی ابزار در API
همهی مدلهاGPT-6.1 Sol
پرچمدار اوپنایآی برای کارهای دقیق، تحلیلی و چندمرحلهای
Gemini 3.8 Flash
سریع، چندوجهی و با حافظهی متنی بسیار بلند
Claude Haiku 5.5
سریعترین کلود؛ در سهمیهی رایگان روزانه
سبک و ارزان؛ در سهمیهی رایگان روزانه
DeepSeek V4.1 Flash
سریع و بسیار ارزان؛ در سهمیهی رایگان روزانه
نمونه پرامپتها
پرامپت را کپی کنید، در 1ai بگذارید و جزئیات خودتان را جایگزین کنید.
پاسخ ساختیافته (JSON)
Extract the invoice number, date and total amount from this Persian text. Return JSON only with the keys invoice_no, date and total. [متن فاکتور]
همراه `response_format={'type': 'json_object'}` بفرستید.
پیام سیستم دستیار فارسی
You are the Persian support assistant of [نام محصول]. Answer in formal Persian in at most five sentences. If you are not sure, say so and suggest contacting support.
آزمایش فراخوانی ابزار
سفارش شمارهی [شماره سفارش] الان در چه وضعیتی است؟
با ابزار get_order_status از نمونه کد بفرستید و ببینید مدل tool_calls برمیگرداند.
متن برای تبدیل به گفتار
سلام! به [نام کسبوکار] خوش آمدید. برای پیگیری سفارش عدد یک و برای گفتگو با پشتیبانی عدد دو را بگیرید.
با `audio.speech` و مدل `openai/tts-1` بفرستید.
پرامپت تصویر
A minimal flat illustration of a Persian teahouse at sunset, warm colors, no text
با `images.generate` و مدل `openai/gpt-image-2` بفرستید.
اتصال OpenAI SDK به 1ai در Python و Node.js
# pip install openai
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='anthropic/claude-sonnet-5.5',
messages=[{'role': 'user', 'content': 'خودت را در یک جمله معرفی کن.'}],
)
print(reply.choices[0].message.content)// npm install openai
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: 'google/gemini-3.8-flash',
messages: [{ role: 'user', content: 'خودت را در یک جمله معرفی کن.' }],
});
console.log(reply.choices[0].message.content);هر دو کتابخانه متغیرهای OPENAI_BASE_URL و OPENAI_API_KEY را هم میخوانند؛ اگر آنها را تنظیم کنید، OpenAI() بدون آرگومان کار میکند. نمونهی اول README رسمی OpenAI با responses.create است؛ با 1ai همیشه chat.completions.create را به کار ببرید. نمونههای پایهتر با cURL در راهنمای API سازگار با OpenAI آمده است.
استریم و فراخوانی ابزار (tool calling)
استریم با گزارش مصرف:
stream = client.chat.completions.create(
model='deepseek/deepseek-v4.1-flash',
messages=[{'role': 'user', 'content': 'یک شعر کوتاه دربارهی باران بنویس.'}],
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='')
if chunk.usage:
print('\n', chunk.usage) # includes creditsفراخوانی ابزار، با یک مدل دارای tools:
import json
tools = [{'type': 'function', 'function': {
'name': 'get_order_status',
'description': 'Get the status of an order by its number',
'parameters': {'type': 'object', 'properties': {'order_id': {'type': 'string'}}, 'required': ['order_id']},
}}]
messages = [{'role': 'user', 'content': 'سفارش 1024 کجاست؟'}]
first = client.chat.completions.create(model='openai/gpt-6.1-sol', messages=messages, tools=tools)
call = first.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)
result = {'order_id': args['order_id'], 'status': 'shipped'}
messages += [first.choices[0].message, {'role': 'tool', 'tool_call_id': call.id, 'content': json.dumps(result)}]
final = client.chat.completions.create(model='openai/gpt-6.1-sol', messages=messages, tools=tools)
print(final.choices[0].message.content)فهرست مدلهایی که از ابزار پشتیبانی میکنند در مدلهای گفتگو و بالای همین صفحه است.
embeddings، تصویر و صدا با همان کلاینت
import base64
emb = client.embeddings.create(model='openai/text-embedding-3-small', input=['سلام دنیا', 'hello world'])
print(len(emb.data[0].embedding))
img = client.images.generate(model='openai/gpt-image-2', prompt='A Persian teahouse at sunset, flat illustration', size='1024x1024')
open('teahouse.png', 'wb').write(base64.b64decode(img.data[0].b64_json))
with client.audio.speech.with_streaming_response.create(model='openai/tts-1', voice='alloy', input='سلام، خوش آمدید.') as res:
res.stream_to_file('welcome.mp3')
text = client.audio.transcriptions.create(model='openai/whisper-1', file=open('voice.m4a', 'rb'))
print(text.text)مدلهای GPT Image تصویر را به شکل base64 برمیگردانند. ساخت تصویر و صدا هم مثل چت از اعتبار حساب کم میشود. ویرایش تصویر (images/edits) در API فعلاً در دسترس نیست.
کدام مدل را برای برنامهی خودتان انتخاب کنیم؟
| نیاز | Model ID پیشنهادی |
|---|---|
| پاسخ دقیق و استدلال | openai/gpt-6.1-sol، anthropic/claude-sonnet-5.5 |
| حجم بالا با هزینهی کم | deepseek/deepseek-v4.1-flash، openai/gpt-5.4-mini |
| متن طولانی و ورودی تصویری | google/gemini-3.8-flash |
| عامل و فراخوانی ابزار | qwen/qwen3.8-max، moonshotai/kimi-k3 |
| بردار متن برای جستوجوی معنایی | openai/text-embedding-3-small |
| تصویر، گفتار و متن از صوت | openai/gpt-image-2، openai/tts-1، openai/whisper-1 |
شناسهی مدل را در کد ثابت ننویسید؛ آن را در تنظیمات یا متغیر محیطی نگه دارید تا بتوانید بدون انتشار دوباره، مدل ارزانتر یا تازهتری را امتحان کنید. یک نمونهی واقعی از ورودیهای خودتان را به دو یا سه مدل بدهید و کیفیت، سرعت و هزینه را کنار هم بگذارید. مقایسهی کلی خانوادهها در مقالهی مقایسهی GPT، Claude و Gemini آمده است.
LangChain و کتابخانههای دیگر
هر کتابخانهای که آدرس پایهی OpenAI را میپذیرد با 1ai کار میکند. در LangChain:
# pip install langchain-openai
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model='anthropic/claude-sonnet-5.5',
base_url='https://1ai.ir/v1',
api_key=os.environ['ONEAI_API_KEY'],
use_responses_api=False,
)
print(llm.invoke('سه ایده برای نام یک کافه بده.').content)use_responses_api=False را بگذارید، چون ChatOpenAI در بعضی حالتها خودش سراغ Responses API میرود. برای ساختن ربات و گردشکار بدون کد، راهنمای n8n را ببینید.
خطاها و کنترل هزینه در کد
| خطای SDK | وضعیت و کد 1ai | راهحل |
|---|---|---|
AuthenticationError | 401 invalid_api_key | کلید یا متغیر محیطی را بررسی کنید |
NotFoundError | 404 model_not_found | پیشوند سازنده را بنویسید |
NotFoundError با Unknown endpoint | 404 not_found | از responses یا مسیر نادرست استفاده شده؛ آدرس باید به /v1 ختم شود |
PermissionDeniedError | 403 model_not_allowed | مدل را به مدلهای مجاز کلید اضافه کنید |
APIStatusError | 402 insufficient_credits یا key_cap_reached | اعتبار یا سقف کلید |
RateLimitError | 429 rate_limit_exceeded | صبر به اندازهی retry-after |
کتابخانه خطاهای 429 و 5xx را بهطور پیشفرض دو بار دوباره میفرستد؛ با max_retries تغییرش دهید. هزینهی هر درخواست را اینطور بخوانید:
raw = client.chat.completions.with_raw_response.create(model='openai/gpt-5.4-mini', messages=[{'role': 'user', 'content': 'Hi'}])
print(raw.headers.get('x-1ai-credits'))
reply = raw.parse()max_tokens را تعیین کنید و برای هر محیط کلید جدا با سقف بسازید. جزئیات در راهنمای کلیدها و کنترل هزینه و نمای کلی API در صفحهی توسعهدهندگان.
ابزارهای آماده
توضیح کد و رفع باگ
کد را بفهمید، خطایش را پیدا کنید و تمیزش کنید
ساخت کوئری SQL
درخواست فارسی، کوئری درست و توضیحدادهشده
دستیارهای مرتبط
برنامهنویس ارشد
نوشتن، مرور و اشکالزدایی کد با توضیح روشن
- «این کد را مرور کن و باگها و مشکلات امنیتیاش را بگو: »
- «یک API ساده برای مدیریت کارها با Node.js و Express بنویس»
سوالات متداول
برای مهاجرت به 1ai چه چیزی در کدم عوض میشود؟
سه چیز: آدرس پایه (https://1ai.ir/v1)، کلید (sk-1ai-…) و شناسهی مدل که پیشوند سازنده میگیرد، مثل openai/gpt-5.4-mini به جای gpt-5.4-mini. اگر جایی از responses.create استفاده کردهاید، آن را به chat.completions.create برگردانید.
کتابخانهی Anthropic یا Google را میشود به 1ai وصل کرد؟
خیر. 1ai فقط API سازگار با OpenAI دارد و مسیر /v1/messages Anthropic را ندارد. Claude و Gemini را هم با همان کتابخانهی openai و شناسههایی مثل anthropic/claude-sonnet-5.5 صدا بزنید.
میتوانم کلید را در کد فرانتاند یا اپ موبایل بگذارم؟
نه. کلیدی که به مرورگر یا اپ برسد عملاً افشا شده است. درخواستها را از سرور خودتان بفرستید و اگر کلیدی لو رفت، از پنل باطلش کنید و کلید تازه بسازید.
تصویر را هم میشود به مدلهای چت فرستاد؟
بله، برای مدلهای دارای vision مثل Claude، GPT و Gemini. در content پیام کاربر، کنار بخش متنی یک بخش image_url با نشانی تصویر یا دادهی base64 بگذارید؛ همان قالب استاندارد OpenAI.
فهرست مدلها را از کد چطور بگیرم؟
client.models.list() مدلهای فعالی را برمیگرداند که کلید شما اجازهی استفاده از آنها را دارد. پاسخ JSON علاوه بر id فیلدهای kind، capabilities، context_window و pricing را هم دارد تا مدل مناسب را در کد انتخاب کنید.
Assistants، Files یا Realtime API کار میکنند؟
خیر. 1ai مسیرهای chat/completions، models، embeddings، images/generations، audio/speech و audio/transcriptions را دارد. برای حافظه و فایل، داده را در سرور خودتان نگه دارید و در پیامها بفرستید.
مطالب مرتبط

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL
چطور پروژهای را که با کتابخانهی OpenAI نوشته شده، فقط با تغییر آدرس پایه و کلید به 1ai وصل کنید؛ با نمونه کد Python، Node.js و cURL، استریم، فهرست مدلها و مدیریت خطا.

کلید API در 1ai: امنیت، محدودیتها و کنترل هزینه
چطور کلیدهای API را امن نگه دارید و هزینه را مهار کنید: مدلهای مجاز، سقف اعتبار ماهانه، محدودیت نرخ، تاریخ انقضا، کلیدهای تیمی و گزارش مصرف.

مقایسه ChatGPT، Claude و Gemini: کدام مدل برای چه کاری؟
سه خانوادهی مطرح مدلهای زبانی، یعنی GPT از OpenAI، Claude از Anthropic و Gemini از گوگل، هر کدام کجا میدرخشند و چطور برای کار خودتان بهترین را انتخاب کنید.

مدل زبانی بزرگ (LLM) چیست؟ راهنمای کاربردی برای فارسی
LLM موتور بسیاری از دستیارهای هوش مصنوعی است. با مثالهای ساده، سازوکار آن، تفاوت مدلهای باز و بسته و روش انتخاب مدل مناسب برای متن و کارهای فارسی را بشناسید.
صفحههای مرتبط
همهی امکاناتاتصال n8n
در n8n یک اعتبارنامهی OpenAI با آدرس 1ai بسازید و در گردشکارهای خودکار، از AI Agent تا ربات تلگرام، با GPT، Claude، Gemini و DeepSeek کار کنید.
اتصال Open WebUI
Open WebUI را روی سرور خودتان بالا بیاورید، یک اتصال OpenAI با آدرس 1ai بسازید و برای کاربرانتان رابط چت با GPT، Claude، Gemini و DeepSeek داشته باشید.
برنامهنویسی با هوش مصنوعی
کد بنویسید، خطا پیدا کنید، SQL و Regex بسازید و با API سازگار با OpenAI مدلها را به ابزارهای خودتان وصل کنید.
OpenAI SDK با API فارسی 1ai؛ نمونه کد Python و Node.js
کتابخانهی رسمی openai را در Python و Node.js با تغییر آدرس پایه به 1ai وصل کنید و چت، فراخوانی ابزار، بردار متن، تصویر و صدا را از یک کلید بگیرید.
ساخت کلید API