راهنمای اتصال به API

OpenAI SDK با API فارسی 1ai؛ نمونه کد Python و Node.js

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

OpenAI SDK با API فارسی 1ai؛ کد Python و Node.js با base_url برابر https://1ai.ir/v1

چرا با 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` را می‌گوید. اعتبار را با پرداخت ریالی می‌خرید.

سقف مصرف برای هر کلید

برای هر محیط، مثل توسعه و تولید، کلید جدا با سقف ماهانه، مدل‌های مجاز و سقف درخواست در دقیقه بسازید.

در چند قدم

  1. ۱

    کتابخانه را نصب کنید

    در Python `pip install openai` و در Node.js `npm install openai` را اجرا کنید.

  2. ۲

    کلید را در متغیر محیطی بگذارید

    کلید `sk-1ai-…` را از بخش توسعه‌دهندگان ← کلیدها بسازید و در `ONEAI_API_KEY` نگه دارید، نه در کد.

  3. ۳

    کلاینت را با آدرس 1ai بسازید

    آدرس پایه را `https://1ai.ir/v1` بگذارید و شناسه‌ی مدل را با پیشوند سازنده بنویسید.

  4. ۴

    از Chat Completions استفاده کنید

    متن را با `chat.completions.create` بگیرید. مسیر `responses.create` در 1ai وجود ندارد.

مدل‌های چت دارای فراخوانی ابزار در API

همه‌ی مدل‌ها

GPT-6.1 Sol

اوپن‌ای‌آی
گفتگو

پرچم‌دار اوپن‌ای‌آی برای کارهای دقیق، تحلیلی و چندمرحله‌ای

۱٫۵ اعتبار / ۱۰۰۰ توکن خروجی
API

Claude Sonnet 5.5

آنتروپیک
گفتگو

نویسندگی روان و برنامه‌نویسی دقیق

۱٫۵ اعتبار / ۱۰۰۰ توکن خروجی
API
گفتگو

سریع، چندوجهی و با حافظه‌ی متنی بسیار بلند

۰٫۵۶۲۵ اعتبار / ۱۰۰۰ توکن خروجی
API

Claude Haiku 5.5

آنتروپیک
گفتگو

سریع‌ترین کلود؛ در سهمیه‌ی رایگان روزانه

۰٫۰۷۵ اعتبار / ۱۰۰۰ توکن خروجی
رایگان روزانهAPI
گفتگو

سبک و ارزان؛ در سهمیه‌ی رایگان روزانه

۰٫۳۷۵ اعتبار / ۱۰۰۰ توکن خروجی
رایگان روزانهAPI

DeepSeek V4.1 Flash

دیپ‌سیک
گفتگو

سریع و بسیار ارزان؛ در سهمیه‌ی رایگان روزانه

۰٫۰۹ اعتبار / ۱۰۰۰ توکن خروجی
رایگان روزانهAPI

نمونه پرامپت‌ها

پرامپت را کپی کنید، در 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

python
# 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)
javascript
// 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)

استریم با گزارش مصرف:

python
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:

python
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، تصویر و صدا با همان کلاینت

python
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:

python
# 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راه‌حل
AuthenticationError401 invalid_api_keyکلید یا متغیر محیطی را بررسی کنید
NotFoundError404 model_not_foundپیشوند سازنده را بنویسید
NotFoundError با Unknown endpoint404 not_foundاز responses یا مسیر نادرست استفاده شده؛ آدرس باید به /v1 ختم شود
PermissionDeniedError403 model_not_allowedمدل را به مدل‌های مجاز کلید اضافه کنید
APIStatusError402 insufficient_credits یا key_cap_reachedاعتبار یا سقف کلید
RateLimitError429 rate_limit_exceededصبر به اندازه‌ی retry-after

کتابخانه خطاهای 429 و 5xx را به‌طور پیش‌فرض دو بار دوباره می‌فرستد؛ با max_retries تغییرش دهید. هزینه‌ی هر درخواست را این‌طور بخوانید:

python
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
توسعه‌دهندگان

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL

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

۴ دقیقه مطالعه
کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه
توسعه‌دهندگان

کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه

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

۴ دقیقه مطالعه
مقایسه ChatGPT، Claude و Gemini: کدام مدل برای چه کاری؟
کاربردها

مقایسه ChatGPT، Claude و Gemini: کدام مدل برای چه کاری؟

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

۴ دقیقه مطالعه
مدل زبانی بزرگ (LLM) چیست؟ راهنمای کاربردی برای فارسی
مفاهیم هوش مصنوعی

مدل زبانی بزرگ (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