نمونه‌کد وب‌سرویس هوش مصنوعی (API) نِت اَرز

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

OpenAI-compatible AI API examples for developers in Iran: one key for GPT, Claude, Gemini and DeepSeek, prepaid in Toman.

معرفی سرویس · مستندات · مدل‌ها و قیمت‌ها · ساخت کلید · English

این مخزن نمونه‌کدهای آماده برای وصل شدن به API هوش مصنوعی نِت اَرز (وب سرویس هوش مصنوعی) را دارد: Python، Node.js، PHP، Laravel، Go، C# (.NET)، Ruby، cURL، LangChain، n8n، ربات تلگرام و ویرایشگرهای کد مثل Cursor و Cline.

اگر با کتابخانهٔ رسمی OpenAI کار کرده‌اید، کد شما تقریباً همان است. فقط دو مقدار عوض می‌شود:

مقدار	در OpenAI	در نِت اَرز
نشانی پایه (base URL)	https://api.openai.com/v1	https://netarz.ir/api/ai/v1
کلید دسترسی (API Key)	sk-proj-…	sk-ntz-v1-…

هزینهٔ هر درخواست به دلار از اعتبار تومانی شما کم می‌شود و کارت ارزی لازم نیست.

روی گیسو هم کار می‌کند. این نمونه‌ها روی گیسو، برند هوش مصنوعی نِت اَرز، هم اجرا می‌شوند: نشانی پایه را https://gisoo.pro/api/v1 بگذارید و کلید sk-gisoo-v1-… یا همان کلید نِت اَرز خودتان را. روی گیسو کتابخانهٔ Anthropic و Claude Code هم وصل می‌شوند.

فهرست

• شروع در دو دقیقه
• پیش از اجرای نمونه‌ها
• فهرست نمونه‌ها
• Go، C# و Ruby
• یک کلید، چهار سازنده
• روی گیسو: Claude Code و کتابخانهٔ Anthropic
• هزینه را کنترل کنید
• کلید را کجا نگه دارید
• خطاهای رایج
• پرسش‌های رایج
• بررسی خودکار کد و فهرست تغییرات
• مخزن‌های دیگر نِت اَرز
• مشارکت و پشتیبانی
• English

شروع در دو دقیقه

۱. فهرست مدل‌ها را ببینید. این درخواست کلید نمی‌خواهد:

curl "https://netarz.ir/api/ai/v1/models?type=chat"

۲. کلید بسازید. در نِت اَرز ثبت‌نام کنید، اعتبار بخرید و در پنل یک کلید بسازید.

۳. اولین درخواست را بفرستید:

git clone https://github.com/netarz/ai-api-examples.git
cd ai-api-examples/python
pip install -r requirements.txt
export NETARZ_API_KEY="sk-ntz-v1-..."
python chat.py

همین کار با Node.js:

cd ai-api-examples/node && npm install
NETARZ_API_KEY="sk-ntz-v1-..." npm run chat

یا در کد خودتان:

from openai import OpenAI

client = OpenAI(base_url="https://netarz.ir/api/ai/v1", api_key="sk-ntz-v1-...")
r = client.chat.completions.create(
    model="gpt-4o-mini",  # یا openrouter/anthropic/claude-sonnet-4.5، gemini-3.5-flash، deepseek-flash
    messages=[{"role": "user", "content": "سلام"}],
    max_tokens=200,
)
print(r.choices[0].message.content)

راهنمای قدم‌به‌قدم: شروع سریع در مستندات

پیش از اجرای نمونه‌ها

1. در نِت اَرز ثبت‌نام کنید و از پنل /ai اعتبار بخرید. حداقل مبلغ شارژ و مالیات بر ارزش افزوده را پیش از پرداخت می‌بینید.
2. در همان پنل یک پروژه و برای آن یک کلید بسازید. کلید کامل را فقط همان یک بار می‌بینید.
3. کلید را در متغیر محیطی بگذارید (فایل .env.example را ببینید):

export NETARZ_API_KEY="sk-ntz-v1-..."

در هیچ فایلی از این مخزن کلید واقعی نیست. کلید خودتان را هم در گیت کامیت نکنید.

فهرست نمونه‌ها

پوشه / فایل	چه کاری می‌کند	راهنمای مربوط
python/chat.py	گفت‌وگوی ساده با کتابخانهٔ openai	Chat Completions
python/stream.py · node/stream.mjs · curl/stream.sh	پاسخ تکه‌به‌تکه (استریم، SSE)	استریم
python/structured_output.py · node/structured-output.mjs	خروجی JSON و JSON Schema	Chat Completions
python/tool_calling.py · node/tools.mjs	فراخوانی تابع (tools) با چرخهٔ کامل	Chat Completions
python/embeddings.py · node/embeddings.mjs	امبدینگ و جست‌وجوی معنایی ساده	امبدینگ
python/images.py	ساخت تصویر با مدل‌های GPT Image	تصویر
python/audio.py	متن به گفتار و گفتار به متن	صوت
python/responses_api.py	Responses API (فقط مدل‌های OpenAI)	Responses API
python/account_and_models.py · curl/models-and-account.sh	فهرست مدل‌ها (بدون کلید) و موجودی حساب	احراز هویت
python/vision.py · node/vision.mjs	فرستادن تصویر به مدل (vision)، با نشانی اینترنتی یا فایلی روی سیستم خودتان	Chat Completions
python/rag_persian.py	RAG فارسی کوچک: امبدینگ، شباهت کسینوسی (cosine similarity) و جوابی که فقط از متن‌های پیداشده می‌آید	امبدینگ
python/usage_and_cost.py	خواندن مصرف توکن از فیلد usage، برآورد هزینه و مبلغ کسرشده با GET /requests/{id} و GET /usage	حساب و مصرف
python/retry_and_errors.py	مدیریت خطا و تلاش دوباره	خطاها
node/	همین نمونه‌ها با Node.js، به‌علاوهٔ server-proxy.mjs که کلید را روی سرور نگه می‌دارد	SDKها
php/	openai-php/client، و cURL خالص برای هاست اشتراکی (معمولی و استریم)	SDKها
laravel/	سرویس NetArzAi با Http لاراول و یک route نمونه	SDKها
go/	Go با net/http و بدون کتابخانهٔ جانبی: گفت‌وگو و استریم	SDKها
dotnet/	C# (.NET 8) با HttpClient و بدون بستهٔ NuGet: گفت‌وگو و استریم	SDKها
ruby/	Ruby با net/http و بدون gem: گفت‌وگو و استریم	SDKها
curl/	همهٔ endpointهای اصلی با cURL	مرجع تعاملی
langchain/	LangChain پایتون: گفت‌وگو، عوض کردن مدل، RAG کوچک	SDKها
telegram-bot/	ربات تلگرام که با مدل جواب می‌دهد	راهنمای ربات تلگرام
integrations/n8n/	workflow آمادهٔ n8n	SDKها
integrations/editors/	Cursor، Cline و Continue	SDKها
providers/	شناسهٔ مدل‌های OpenAI، Claude، Gemini و DeepSeek با یک نمونه برای هر کدام	مدل‌ها و قیمت‌ها

ساخت ویدیو (Sora) و موسیقی (Lyria) نمونه‌کد جدا در این مخزن ندارند؛ نمونهٔ کامل هر دو در مستندات است: ویدیو · موسیقی.

Go، C# و Ruby

این سه نمونه فقط از کتابخانهٔ استاندارد همان زبان استفاده می‌کنند و کلید را از متغیر محیطی NETARZ_API_KEY می‌خوانند. هر کدام یک گفت‌وگوی ساده و یک نمونهٔ استریم دارد.

export NETARZ_API_KEY="sk-ntz-v1-..."

# Go 1.21+
(cd go && go run ./chat && go run ./stream)

# .NET 8
(cd dotnet && dotnet run && dotnet run -- stream)

# Ruby 3.0+
(cd ruby && ruby chat.rb && ruby stream.rb)

اگر کتابخانهٔ رسمی OpenAI را برای Go یا .NET ترجیح می‌دهید، همان کتابخانه هم کار می‌کند؛ فقط نشانی پایه را https://netarz.ir/api/ai/v1 بگذارید. نمونهٔ کتابخانهٔ Go در صفحهٔ SDKها آمده است.

یک کلید، چهار سازنده

سازنده	شناسهٔ نمونه	نکته	صفحه
OpenAI	gpt-4o-mini	مدل‌های Pro و Codex فقط با /responses	API OpenAI در ایران
Claude	openrouter/anthropic/claude-sonnet-4.5	فقط با پیشوند openrouter/anthropic/؛ کتابخانهٔ Anthropic روی این نشانی کار نمی‌کند، روی گیسو کار می‌کند	API کلود
Gemini	gemini-3.5-flash	Imagen (تصویرساز گوگل) روی درگاه نیست	API جمینای
DeepSeek	deepseek-flash	R1 و بقیه با پیشوند openrouter/deepseek/	API دیپ‌سیک

جزئیات و قاعدهٔ شناسه‌ها در providers/README.md. فهرست زندهٔ مدل‌ها را بدون کلید بگیرید: curl "https://netarz.ir/api/ai/v1/models?type=chat". قیمت هر مدل به دلار و تومان در صفحهٔ مدل‌ها است.

روی گیسو: Claude Code و کتابخانهٔ Anthropic

گیسو برند هوش مصنوعی نِت اَرز است: اپ فارسی برای گفت‌وگو با بیش از ۴۰۰ مدل، ساخت تصویر، ویدیو، موسیقی و صدا، کارشناس‌های هوش مصنوعی و گفت‌وگوی صوتی زنده، به‌علاوهٔ همین وب‌سرویس روی نشانی خودش. حساب و اعتبار هوش مصنوعی در هر دو سایت یکی است و کلیدها جابه‌جا کار می‌کنند: sk-ntz-v1-… روی گیسو و sk-gisoo-v1-… روی نِت اَرز.

	نِت اَرز	گیسو
نشانی پایه	https://netarz.ir/api/ai/v1	https://gisoo.pro/api/v1
قالب OpenAI (همهٔ نمونه‌های این مخزن)	دارد	دارد
Messages API شرکت Anthropic (/messages)	ندارد	دارد
Claude Code و کتابخانهٔ رسمی Anthropic	ندارد	دارد

برای اجرای نمونه‌های این مخزن روی گیسو نشانی پایه را عوض کنید. بیشتر نمونه‌ها آن را از NETARZ_BASE_URL می‌خوانند؛ در نمونه‌های curl/ و providers/ نشانی در خود فایل نوشته شده و همان‌جا عوضش کنید:

export NETARZ_BASE_URL="https://gisoo.pro/api/v1"
export NETARZ_API_KEY="sk-gisoo-v1-..."   # یا همان کلید sk-ntz-v1- خودتان
python python/chat.py

Claude Code با گیسو (نشانی بدون /v1):

export ANTHROPIC_BASE_URL="https://gisoo.pro/api"
export ANTHROPIC_AUTH_TOKEN="sk-gisoo-v1-..."
export ANTHROPIC_MODEL="claude-sonnet-5-5"
claude

نمونه‌کدهای Claude Code، کتابخانهٔ Anthropic (Python و Node.js) و ساخت ویدیو و موسیقی در مخزن netarz/gisoo است. راهنما: gisoo.pro/docs/anthropic · اپ گیسو: gisoo.pro/app

هزینه را کنترل کنید

• همیشه max_tokens بفرستید. پیش از هر درخواست، درگاه مبلغ بلندترین جواب ممکن را از اعتبار شما کنار می‌گذارد؛ با max_tokens این مبلغ کوچک می‌شود و با موجودی کم به خطای insufficient_credit نمی‌خورید. بعد از جواب، فقط مصرف واقعی کم می‌شود.
• درخواستی که پیش از تولید جواب با خطا تمام شود هزینه ندارد. اگر استریم وسط کار قطع شود، فقط آنچه تا آن لحظه تولید شده حساب می‌شود.
• برای هر کلید سقف هزینه و برای هر پروژه بودجهٔ ماهانه بگذارید تا یک باگ یا کلید لورفته کل اعتبار را خرج نکند.
• برای جواب‌های طولانی و مدل‌های استدلالی از استریم استفاده کنید تا اتصال وسط کار قطع نشود.

کلید را کجا نگه دارید

کلید sk-ntz-v1-… را فقط روی سرور نگه دارید؛ نه در کد مرورگر، نه در اپ موبایل، نه در مخزن عمومی. هر کسی کلید را ببیند می‌تواند با اعتبار شما درخواست بفرستد. الگوی درست: مرورگر یا اپ به سرور خودتان درخواست می‌دهد و سرور شما با کلید به نِت اَرز وصل می‌شود (node/server-proxy.mjs، laravel/routes-example.php). برای کلیدهای سرور، فهرست IPهای مجاز را هم در پنل پر کنید.

خطاهای رایج

کد	یعنی	چه کنید
401 missing_api_key / invalid_api_key	کلید نرسیده یا اشتباه است	هدر Authorization: Bearer sk-ntz-v1-… را بررسی کنید
402 insufficient_credit	اعتبار برای رزرو این درخواست کافی نیست	شارژ کنید یا max_tokens را کم کنید
403 model_not_allowed	مدل در فهرست مجاز کلید یا پروژه نیست	هر دو فهرست را در پنل ببینید
404 model_not_found	شناسهٔ مدل پیدا نشد	برای Claude پیشوند openrouter/anthropic/ را بگذارید
429 rate_limit_exceeded	بیش از سقف درخواست در دقیقه	به اندازهٔ Retry-After صبر کنید؛ سقف کلید را GET /me نشان می‌دهد

فهرست کامل: netarz.ir/docs/ai/errors

پرسش‌های رایج

با کتابخانهٔ Anthropic یا مسیر /v1/messages کار می‌کند؟ روی نشانی نِت اَرز نه؛ آن‌جا Claude را با کتابخانهٔ OpenAI و مسیر /chat/completions صدا بزنید. روی نشانی گیسو (https://gisoo.pro/api) کتابخانهٔ Anthropic و Claude Code با همان اعتبار کار می‌کنند؛ بخش روی گیسو را ببینید.

مدل رایگان دارید؟ نه. مدل‌های رایگان روی ظرفیت مشترک ارائه‌دهنده بودند و وسط کار خطا می‌دادند، پس آن‌ها را برداشتیم. قیمت هر مدل را در صفحهٔ مدل‌ها ببینید و مدلی را که به بودجهٔ پروژه‌تان می‌خورد انتخاب کنید.

متن پیام‌هایم جایی ذخیره می‌شود؟ درگاه فقط فراداده ثبت می‌کند، مثل مدل، تعداد توکن، هزینه، وضعیت و زمان. متن پیام‌ها و جواب‌ها در نِت اَرز ذخیره نمی‌شود. بدنهٔ درخواست بدون تغییر به سرویس‌دهندهٔ اصلی (مثل OpenAI، گوگل، DeepSeek یا OpenRouter) می‌رود و از آن‌جا سیاست نگهداری داده‌های همان شرکت حاکم است. جزئیات: حریم خصوصی داده در API هوش مصنوعی

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

بررسی خودکار کد و فهرست تغییرات

با هر Push و Pull Request، گردش‌کار CI نحو (syntax) همهٔ نمونه‌ها را بررسی می‌کند و نمونه‌های Go و .NET را می‌سازد (build). این بررسی هیچ درخواستی به API نمی‌فرستد و کلید لازم ندارد، پس هیچ اعتباری مصرف نمی‌کند. Dependabot هم ماهی یک بار نسخهٔ تازهٔ وابستگی‌ها را پیشنهاد می‌دهد.

تغییرات هر نسخه در CHANGELOG.md آمده است.

مخزن‌های دیگر نِت اَرز

مخزن	چیست
gisoo	گیسو، برند هوش مصنوعی نِت اَرز: معرفی اپ و نمونه‌کد Claude Code، کتابخانهٔ Anthropic، ساخت ویدیو و موسیقی (gisoo.pro)
fx-api-examples	نمونه‌کد وب‌سرویس نرخ ارز: نرخ دلار و ارزها به تومان در PHP، JavaScript، Python، Laravel، Google Sheets و Excel
netarz-fx-wordpress	افزونهٔ وردپرس نرخ ارز با شورت‌کد [netarz_rate currency="usd"] و ابزارک
netarz	معرفی همهٔ وب‌سرویس‌ها و مخزن‌های نِت اَرز

همهٔ پروژه‌های متن‌باز ما یک‌جا: netarz.ir/open-source · همهٔ مستندات فنی: netarz.ir/docs

مشارکت و پشتیبانی

• اشکال در کد همین مخزن: یک Issue باز کنید. قالب گزارش اشکال می‌پرسد چه اجرا کردید و چه دیدید.
• نمونهٔ تازه یا اصلاح: Pull Request بفرستید. پیش از آن راهنمای مشارکت را ببینید.
• حساب، اعتبار و کلید: این‌ها جای Issue نیستند. از پنل نِت اَرز تیکت بزنید یا به info@netarz.ir ایمیل بفرستید.
• مشکل امنیتی: در Issue عمومی ننویسید؛ طبق سیاست امنیتی به dev@netarz.ir بفرستید.

«نِت اَرز» مرکز خرید سرویس‌های خارجی است و نمایندهٔ رسمی هیچ‌یک از شرکت‌هایی که نامشان در این مخزن آمده نیست. نام‌ها و نشان‌های OpenAI، Anthropic، Google و DeepSeek متعلق به خود این شرکت‌هاست.

مجوز: MIT · آیین رفتار

---

English

NetArz AI API examples. Ready-to-run code for the NetArz AI gateway, an OpenAI-compatible API that lets developers in Iran call GPT, Claude, Gemini and DeepSeek models with one key, paying from credit bought in Toman. There are no free models: every call is paid from your prepaid credit.

• Quick start
• Examples
• Go, C# and Ruby
• Facts
• CI and changelog
• Links

Quick start

# 1. No key needed: list the chat models
curl "https://netarz.ir/api/ai/v1/models?type=chat"

# 2. Create a key at https://netarz.ir/ai, then:
git clone https://github.com/netarz/ai-api-examples.git
cd ai-api-examples/python && pip install -r requirements.txt
export NETARZ_API_KEY="sk-ntz-v1-..."
python chat.py

Examples

Folder / file	What it shows
python/	Chat, streaming, JSON output, tool calling, embeddings, images, audio, Responses API, account and models, retries
python/vision.py · node/vision.mjs	Image input (vision) from a URL or a local file
python/rag_persian.py	A small Persian RAG: embeddings, cosine similarity in plain Python, grounded answer
python/usage_and_cost.py	Token usage, a cost estimate from /models prices, the charged amount from /requests/{id} and /usage
node/	The same with Node.js, plus a server-side proxy that keeps the key off the browser
php/ · laravel/	openai-php/client, plain cURL, and a Laravel service
go/ · dotnet/ · ruby/	Chat and streaming with each language's standard library only
curl/	Shell scripts for the main endpoints
langchain/ · telegram-bot/ · integrations/	LangChain, a Telegram bot, n8n, Cursor, Cline and Continue

Go, C# and Ruby

Standard library only; the key is read from NETARZ_API_KEY.

(cd go && go run ./chat && go run ./stream)          # Go 1.21+
(cd dotnet && dotnet run && dotnet run -- stream)    # .NET 8
(cd ruby && ruby chat.rb && ruby stream.rb)          # Ruby 3.0+

Facts

• Base URL: https://netarz.ir/api/ai/v1
• Auth: Authorization: Bearer sk-ntz-v1-… (or X-API-Key)
• Works with the official OpenAI SDKs (Python, Node), openai-php/client, LangChain, n8n, Continue, Cline, Cursor.
• Endpoints: /chat/completions, /completions, /responses (OpenAI models only), /embeddings, /images/generations, /audio/speech, /audio/transcriptions, /audio/translations, /audio/music, /videos (an async job: create, poll, download), /models, /me, /usage, /requests/{id}. /moderations exists but has no active model at the moment.
• Model ids: OpenAI, Gemini and DeepSeek direct ids have no prefix (gpt-4o-mini, gemini-3.5-flash, deepseek-flash); Claude is available only via OpenRouter as openrouter/anthropic/<model>; every other OpenRouter model is openrouter/<vendor>/<model>. Live list, no key needed: GET https://netarz.ir/api/ai/v1/models?type=chat (type = chat, embedding, image, audio_tts, audio_stt, video, music).
• Errors follow OpenAI's shape {"error": {"message", "type", "code", "param"}}; a call that fails before any output is not charged (an interrupted stream is billed for what was generated).
• Send max_tokens: credit for the largest possible answer is reserved before each call.
• Gisoo (our AI brand) serves the same gateway at https://gisoo.pro/api/v1; keys work on both. Gisoo also speaks Anthropic's Messages API, so the Anthropic SDKs and Claude Code work there (ANTHROPIC_BASE_URL=https://gisoo.pro/api). Set NETARZ_BASE_URL=https://gisoo.pro/api/v1 to run these examples against it (the curl/ and providers/ files have the URL written in, change it there). Examples: netarz/gisoo.
• Keep the key on your server. NetArz stores only metadata, not prompts or completions; the request body is forwarded unchanged to the upstream provider, whose own retention policy then applies.

CI and changelog

CI checks the syntax of every example and builds the Go and .NET projects on each push and pull request. It never calls the API and uses no key. Dependabot proposes dependency updates monthly. Release notes are in CHANGELOG.md.

Links

• Service overview: netarz.ir/ai-api
• Docs: netarz.ir/docs/ai · Migrating from OpenAI: netarz.ir/docs/ai/migrating-from-openai
• Models and prices: netarz.ir/ai-api/models
• All NetArz open-source projects: netarz.ir/open-source
• Gisoo, our Persian AI app and API: gisoo.pro · Claude Code guide · netarz/gisoo
• Related repos: fx-api-examples (Toman exchange rate API) · netarz-fx-wordpress (WordPress plugin)

Contributions are welcome: see CONTRIBUTING.md. Report security issues privately to dev@netarz.ir (SECURITY.md). NetArz is a marketplace for buying foreign services and is not an official representative of OpenAI, Anthropic, Google or DeepSeek. Licensed under MIT.