آموزش و راهنما

آموزش استفاده از API درواره با cURL؛ تست مدل‌های هوش مصنوعی در Terminal

در این راهنمای عملی، استفاده از API درواره با cURL را از صفر می‌آموزید؛ از دریافت مدل‌ها و ارسال Chat تا Streaming، Vision، Structured Outputs، Tool Calling، مدیریت خطا و پردازش پاسخ با jq در Windows، Linux و macOS.

Darvareh API - cURL

مقدمه

برای آزمایش API مدل‌های هوش مصنوعی همیشه به Postman، محیط برنامه‌نویسی یا ساخت یک اپلیکیشن کامل نیاز ندارید. با یک ابزار خط فرمان به نام cURL می‌توانید مستقیماً از Terminal یا Command Prompt به API درخواست بفرستید و پاسخ را دریافت کنید.

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

بررسی اعتبار API Key
دریافت فهرست مدل‌ها
ارسال Prompt
آزمایش System Prompt
تست Streaming
ارسال تصویر به مدل‌های Vision
دریافت خروجی JSON
آزمایش Tool Calling
اندازه‌گیری زمان پاسخ
ذخیره Response در فایل
بررسی Headerها و Status Code
اجرای درخواست روی سرور Linux
استفاده در Script و فرایندهای خودکار
انتقال درخواست به Postman یا زبان‌های برنامه‌نویسی

در این مقاله، استفاده از API سازگار با OpenAI درواره را با cURL به‌صورت مرحله‌به‌مرحله آموزش می‌دهیم. مثال‌ها برای Linux، macOS و Windows ارائه می‌شوند و نکات امنیتی لازم برای جلوگیری از افشای API Key نیز بررسی خواهند شد.

فهرست مطالب

cURL چیست؟
چرا از cURL برای API هوش مصنوعی استفاده کنیم؟
ساختار یک فرمان cURL
نصب و بررسی cURL
تفاوت cURL در Windows و PowerShell
پیش‌نیازهای اتصال به درواره
نگهداری امن API Key
دریافت فهرست مدل‌ها
ارسال اولین Chat Completion
استفاده از System Prompt
ارسال تاریخچه مکالمه
استفاده از فایل JSON
پردازش پاسخ با jq
ذخیره پاسخ در فایل
مشاهده Headerها و Status Code
اندازه‌گیری زمان پاسخ
تست Streaming
ارسال تصویر با URL
ارسال تصویر Base64
آزمایش JSON Mode
آزمایش Structured Outputs
تست Tool Calling
ادامه درخواست پس از Tool Call
آزمایش تولید تصویر
تنظیم Timeout
Retry و مدیریت خطا
استفاده از فایل تنظیمات cURL
تبدیل cURL به Postman و کد
ساخت Script آماده
نکات امنیتی
چک‌لیست
پرسش‌های متداول
جمع‌بندی

cURL چیست؟

cURL یک ابزار خط فرمان برای انتقال داده به سرور یا دریافت داده از آن با استفاده از URL است. این ابزار از پروتکل‌های متعددی از جمله HTTP و HTTPS پشتیبانی می‌کند و یکی از متداول‌ترین ابزارها برای آزمایش REST APIهاست.

نام cURL معمولاً به ابزار خط فرمان curl اشاره دارد و قابلیت‌های انتقال آن توسط کتابخانه libcurl فراهم می‌شوند. مستندات رسمی cURL

یک درخواست ساده HTTP با cURL می‌تواند چنین باشد:

curl https://example.com

برای APIهای احراز هویت‌شده می‌توان Header و Body نیز اضافه کرد:

curl https://api.example.com/v1/messages \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"سلام"}'

چرا از cURL برای API هوش مصنوعی استفاده کنیم؟

تقریباً همه‌جا در دسترس است

cURL روی بسیاری از سیستم‌های Linux، macOS و نسخه‌های جدید Windows نصب است یا به‌سادگی نصب می‌شود.

به رابط گرافیکی نیاز ندارد

می‌توانید آن را روی سرور، VPS، Container یا محیط SSH اجرا کنید.

برای Debug مناسب است

Request و Response را بدون لایه‌های اضافی SDK بررسی می‌کنید.

قابل انتقال است

یک فرمان cURL را می‌توان:

در مستندات قرار داد؛
وارد Postman کرد؛
به Python یا JavaScript تبدیل کرد؛
داخل Script استفاده کرد؛
در CI/CD اجرا کرد.

برای آزمایش سریع مناسب است

تغییر مدل، Prompt یا Header فقط با ویرایش یک فرمان انجام می‌شود.

برای اتوماسیون مناسب است

می‌توان Response را به jq، فایل، Script یا فرمان دیگری فرستاد.

cURL چه جایگاهی در پروژه Production دارد؟

cURL برای تست، Debug، اسکریپت‌های ساده و مدیریت عملیات بسیار مفید است، اما به‌تنهایی معماری Production محسوب نمی‌شود.

در یک اپلیکیشن واقعی همچنان به این موارد نیاز دارید:

نگهداری امن Secret
Authentication کاربران
Rate Limit
Timeout
Retry
Validation
Billing
Logging
Monitoring
Idempotency
Queue
مدیریت Context
امنیت Tool Calling

cURL ابزار فراخوانی API است، نه جایگزین Backend کامل.

ساختار یک فرمان cURL

یک فرمان cURL برای API معمولاً از اجزای زیر ساخته می‌شود:

curl METHOD_AND_URL \
  -H "HEADER_1" \
  -H "HEADER_2" \
  -d 'JSON_BODY'

URL

https://api.darvareh.ir/v1/chat/completions

Method

-X POST

یا:

--request POST

اگر از -d استفاده کنید، cURL معمولاً درخواست را به‌صورت POST ارسال می‌کند؛ اما نوشتن صریح Method خوانایی را بهتر می‌کند.

فرم کوتاه:

-H "Content-Type: application/json"

فرم کامل:

--header "Content-Type: application/json"

Body

فرم کوتاه:

-d '{"key":"value"}'

فرم کامل:

--data '{"key":"value"}'

ادامه فرمان در خط بعد

در Bash و Zsh از Backslash استفاده می‌شود:

curl https://example.com \
  -H "Content-Type: application/json"

در PowerShell از Backtick استفاده می‌شود:

curl.exe https://example.com `
  -H "Content-Type: application/json"

در Windows Command Prompt از ^ استفاده می‌شود:

curl.exe https://example.com ^
  -H "Content-Type: application/json"

بررسی نصب cURL

Terminal را باز کنید و بنویسید:

curl --version

اگر cURL نصب باشد، اطلاعاتی مشابه این نمایش داده می‌شود:

curl 8.x.x
Protocols: http https ...
Features: ...

نصب cURL در Linux

Ubuntu و Debian

sudo apt update
sudo apt install curl

Fedora

sudo dnf install curl

CentOS و RHEL

بسته به نسخه:

sudo dnf install curl

یا:

sudo yum install curl

Arch Linux

sudo pacman -S curl

پس از نصب:

curl --version

نصب cURL در macOS

در بسیاری از نسخه‌های macOS، cURL از قبل نصب است:

curl --version

اگر بخواهید نسخه دیگری را با Homebrew نصب کنید:

brew install curl

ممکن است نسخه نصب‌شده Homebrew در مسیر متفاوتی قرار گیرد. برای بیشتر تست‌های این مقاله نسخه پیش‌فرض سیستم کافی است.

استفاده از cURL در Windows

نسخه‌های جدید Windows معمولاً curl.exe را همراه سیستم دارند.

در PowerShell یا Command Prompt اجرا کنید:

curl.exe --version

تفاوت `curl` و `curl.exe` در PowerShell

در Windows PowerShell 5.1، عبارت curl ممکن است Alias مربوط به Invoke-WebRequest باشد و رفتار متفاوتی از cURL واقعی داشته باشد.

برای اطمینان از اجرای cURL واقعی، از این فرمان استفاده کنید:

curl.exe

Microsoft نیز توصیه می‌کند در Windows PowerShell 5.1 از curl.exe استفاده کنید یا Alias را حذف کنید. در PowerShell 7 به بعد این Alias به‌صورت پیش‌فرض وجود ندارد. راهنمای cURL در Windows

تمام مثال‌های Windows این مقاله با curl.exe نوشته می‌شوند.

نصب jq

jq ابزاری برای خواندن، فیلترکردن و تبدیل JSON در خط فرمان است. استفاده از آن الزامی نیست، اما پاسخ‌های API را بسیار خواناتر می‌کند.

وب‌سایت رسمی jq آن را ابزاری برای برش، فیلتر، نگاشت و تبدیل داده JSON معرفی می‌کند. مستندات jq

Ubuntu و Debian

sudo apt update
sudo apt install jq

Fedora

sudo dnf install jq

macOS

brew install jq

Windows با Winget

winget install jqlang.jq

بررسی نصب

jq --version

پیش‌نیازهای اتصال به API درواره

برای اجرای مثال‌ها به موارد زیر نیاز دارید:

حساب درواره
API Key معتبر
اعتبار کافی
شناسه یک مدل فعال
cURL
در صورت نیاز jq

Base URL درواره:

https://api.darvareh.ir/v1

Endpointهای اصلی این آموزش:

GET /models
POST /chat/completions

URL کامل:

https://api.darvareh.ir/v1/models

https://api.darvareh.ir/v1/chat/completions

روش احراز هویت

API Key به‌صورت Bearer Token ارسال می‌شود:

Authorization: Bearer YOUR_DARVAREH_API_KEY

در cURL:

-H "Authorization: Bearer YOUR_DARVAREH_API_KEY"

برای درخواست JSON:

-H "Content-Type: application/json"

استفاده مستقیم از API Key

برای یک آزمایش سریع می‌توان نوشت:

curl https://api.darvareh.ir/v1/models \
  -H "Authorization: Bearer YOUR_DARVAREH_API_KEY"

اما این روش برای استفاده مستمر توصیه نمی‌شود، زیرا API Key ممکن است در موارد زیر باقی بماند:

Shell History
Screenshot
Log
Script
مستندات
Process List در برخی شرایط
ابزارهای ضبط Terminal

بهتر است از متغیر محیطی استفاده کنید.

تنظیم API Key در Linux و macOS

در Bash یا Zsh:

export DARVAREH_API_KEY="YOUR_DARVAREH_API_KEY"

Base URL:

export DARVAREH_BASE_URL="https://api.darvareh.ir/v1"

شناسه مدل:

export DARVAREH_MODEL="MODEL_ID"

استفاده:

curl "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

این متغیرها معمولاً فقط در همان Session ترمینال فعال‌اند.

برای حذف API Key:

unset DARVAREH_API_KEY

تنظیم API Key در PowerShell

$env:DARVAREH_API_KEY = "YOUR_DARVAREH_API_KEY"

$env:DARVAREH_BASE_URL = "https://api.darvareh.ir/v1"

$env:DARVAREH_MODEL = "MODEL_ID"

استفاده:

curl.exe "$env:DARVAREH_BASE_URL/models" `
  -H "Authorization: Bearer $env:DARVAREH_API_KEY"

حذف متغیر:

Remove-Item Env:DARVAREH_API_KEY

تنظیم API Key در Command Prompt

set DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY

set DARVAREH_BASE_URL=https://api.darvareh.ir/v1

set DARVAREH_MODEL=MODEL_ID

استفاده:

curl.exe "%DARVAREH_BASE_URL%/models" ^
  -H "Authorization: Bearer %DARVAREH_API_KEY%"

این متغیرها در همان پنجره Command Prompt فعال‌اند.

نکته امنیتی درباره فایل‌های Shell

قرار‌دادن API Key در فایل‌هایی مانند موارد زیر ممکن است باعث نگهداری دائمی Secret شود:

.bashrc
.zshrc
.profile
PowerShell profile

برای سیستم شخصی کنترل‌شده ممکن است قابل‌استفاده باشد، اما برای سرور و تیم بهتر است از Secret Manager، فایل امن خارج از Git یا ابزارهای مدیریت Credential استفاده شود.

دریافت فهرست مدل‌ها

Linux و macOS

curl "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

PowerShell

curl.exe "$env:DARVAREH_BASE_URL/models" `
  -H "Authorization: Bearer $env:DARVAREH_API_KEY"

بدون متغیر

curl https://api.darvareh.ir/v1/models \
  -H "Authorization: Bearer YOUR_DARVAREH_API_KEY"

پاسخ احتمالی

{
  "object": "list",
  "data": [
    {
      "id": "MODEL_ID",
      "object": "model"
    }
  ]
}

ساختار دقیق Metadata ممکن است با نسخه فعلی API متفاوت باشد.

نمایش خوانای فهرست مدل‌ها با jq

curl -sS "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" |
jq

گزینه‌ها:

-s خروجی Progress را مخفی می‌کند.
-S همچنان خطاهای cURL را نمایش می‌دهد.
| jq پاسخ JSON را قالب‌بندی می‌کند.

فقط شناسه مدل‌ها

curl -sS "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" |
jq -r '.data[].id'

گزینه -r یا --raw-output رشته را بدون نقل‌قول JSON نمایش می‌دهد.

مرتب‌سازی شناسه‌ها

curl -sS "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" |
jq -r '.data[].id' |
sort

جست‌وجو در مدل‌ها

برای مثال:

curl -sS "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" |
jq -r '.data[].id' |
grep -i "MODEL_NAME"

در PowerShell می‌توانید از Select-String استفاده کنید:

curl.exe -sS "$env:DARVAREH_BASE_URL/models" `
  -H "Authorization: Bearer $env:DARVAREH_API_KEY" |
jq -r ".data[].id" |
Select-String "MODEL_NAME"

ذخیره فهرست مدل‌ها در فایل

curl -sS "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -o models.json

نمایش فایل:

jq . models.json

گزینه -o پاسخ را در فایل ذخیره می‌کند.

ارسال اولین Chat Completion

Linux و macOS

curl "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$DARVAREH_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "هوش مصنوعی را در سه جمله ساده توضیح بده."
      }
    ]
  }'

ترکیب نقل‌قول‌ها در Bash برای قراردادن Variable داخل JSON کمی دشوار است. روش بهتر استفاده از فایل JSON یا jq برای ساخت Body است که در ادامه توضیح می‌دهیم.

PowerShell

در PowerShell استفاده از Here-string ساده‌تر است:

$body = @"
{
  "model": "$env:DARVAREH_MODEL",
  "messages": [
    {
      "role": "user",
      "content": "هوش مصنوعی را در سه جمله ساده توضیح بده."
    }
  ]
}
"@

curl.exe "$env:DARVAREH_BASE_URL/chat/completions" `
  -H "Authorization: Bearer $env:DARVAREH_API_KEY" `
  -H "Content-Type: application/json" `
  --data-raw $body

Command Prompt

در Command Prompt، نوشتن JSON چندخطی دشوار است. استفاده از فایل request.json پیشنهاد می‌شود:

curl.exe "%DARVAREH_BASE_URL%/chat/completions" ^
  -H "Authorization: Bearer %DARVAREH_API_KEY%" ^
  -H "Content-Type: application/json" ^
  --data-binary "@request.json"

پاسخ Chat Completions

پاسخ احتمالی:

{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "هوش مصنوعی..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 22,
    "completion_tokens": 65,
    "total_tokens": 87
  }
}

فیلدهای دقیق پاسخ و Usage ممکن است براساس مدل یا Provider تفاوت داشته باشند.

نمایش فقط متن پاسخ

curl -sS "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json |
jq -r '.choices[0].message.content'

نمایش Usage

curl -sS "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json |
jq '.usage'

فقط مجموع Tokenها

... | jq '.usage.total_tokens'

مدل واقعی پاسخ

... | jq -r '.model'

دلیل توقف

... | jq -r '.choices[0].finish_reason'

ساخت فایل JSON درخواست

فایلی با نام زیر بسازید:

chat-request.json

محتوا:

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "هوش مصنوعی را در سه جمله ساده توضیح بده."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 500
}

ارسال فایل:

curl "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @chat-request.json

چرا `--data-binary`؟

برای JSON معمولی، -d @file نیز کار می‌کند؛ اما --data-binary @file محتوا را بدون تغییرات مرتبط با پردازش داده ارسال می‌کند و برای انتقال دقیق فایل انتخاب روشنی است.

مزایای Body در فایل

مدیریت نقل‌قول‌ها ساده‌تر است.
متن فارسی خواناتر باقی می‌ماند.
JSON را می‌توان Validate کرد.
Request قابل‌استفاده مجدد است.
Command در Windows ساده‌تر می‌شود.
Promptهای طولانی بهتر مدیریت می‌شوند.

نکته امنیتی

اگر فایل شامل داده محرمانه است:

آن را داخل Git قرار ندهید.
Permission فایل را محدود کنید.
پس از پایان حذف کنید.
از ارسال آن در پیام یا Issue خودداری کنید.

بررسی معتبر‌بودن JSON با jq

jq empty chat-request.json

اگر JSON معتبر باشد، خروجی خاصی نمایش داده نمی‌شود.

برای نمایش فرمت‌شده:

jq . chat-request.json

استفاده از System Prompt

فایل system-prompt.json:

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "شما یک مدرس باتجربه برنامه‌نویسی هستید. پاسخ را ساده، دقیق و به زبان فارسی بنویسید."
    },
    {
      "role": "user",
      "content": "تفاوت API و SDK چیست؟"
    }
  ],
  "temperature": 0.2,
  "max_tokens": 700
}

ارسال:

curl -sS "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @system-prompt.json |
jq -r '.choices[0].message.content'

ارسال تاریخچه مکالمه

API Chat Completions معمولاً مکالمه قبلی را به‌صورت خودکار به خاطر نمی‌سپارد. باید پیام‌های موردنیاز را دوباره ارسال کنید.

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "پاسخ را کوتاه و فارسی بنویس."
    },
    {
      "role": "user",
      "content": "RAG چیست؟"
    },
    {
      "role": "assistant",
      "content": "RAG روشی برای بازیابی اطلاعات مرتبط و افزودن آن‌ها به Context مدل پیش از تولید پاسخ است."
    },
    {
      "role": "user",
      "content": "تفاوت آن با Fine-tuning چیست؟"
    }
  ],
  "temperature": 0.2,
  "max_tokens": 700
}

افزایش تاریخچه باعث افزایش Token ورودی، هزینه و Latency می‌شود. در اپلیکیشن واقعی باید Context مدیریت و در صورت لزوم خلاصه شود.

ساخت JSON پویا با jq

به‌جای ترکیب پیچیده نقل‌قول‌های Shell، می‌توانید Body را با jq بسازید.

jq -n \
  --arg model "$DARVAREH_MODEL" \
  --arg prompt "API چیست؟" \
  '{
    model: $model,
    messages: [
      {
        role: "user",
        content: $prompt
      }
    ],
    temperature: 0.2,
    max_tokens: 500
  }'

ارسال مستقیم:

jq -n \
  --arg model "$DARVAREH_MODEL" \
  --arg prompt "API چیست؟" \
  '{
    model: $model,
    messages: [
      {
        role: "user",
        content: $prompt
      }
    ],
    temperature: 0.2,
    max_tokens: 500
  }' |
curl -sS "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- |
jq -r '.choices[0].message.content'

@- یعنی Body از Standard Input خوانده شود.

ذخیره پاسخ در فایل

curl -sS "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @chat-request.json \
  -o response.json

نمایش:

jq . response.json

استخراج متن:

jq -r '.choices[0].message.content' response.json

ذخیره فقط متن:

jq -r '.choices[0].message.content' response.json \
  > answer.txt

مشاهده Response Headers

برای نمایش Headerها همراه با Body:

curl -i "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

گزینه -i Headerهای Response را نیز در خروجی قرار می‌دهد.

فقط Headerها

curl -sS -D - -o /dev/null \
  "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

توضیح:

-D - Headerها را روی Standard Output می‌نویسد.
-o /dev/null Body را کنار می‌گذارد.

در Windows:

curl.exe -sS -D - -o NUL `
  "$env:DARVAREH_BASE_URL/models" `
  -H "Authorization: Bearer $env:DARVAREH_API_KEY"

ذخیره Headerها در فایل

curl -sS \
  -D headers.txt \
  -o response.json \
  "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

نمایش HTTP Status Code

curl -sS \
  -o response.json \
  -w "%{http_code}\n" \
  "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

خروجی:

Body در response.json ذخیره می‌شود.

نمایش Status و زمان

curl -sS \
  -o response.json \
  -w "status=%{http_code}\ntime=%{time_total}s\n" \
  "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

اندازه‌گیری زمان‌های مختلف

curl -sS \
  -o response.json \
  -w '
status: %{http_code}
dns: %{time_namelookup}s
connect: %{time_connect}s
tls: %{time_appconnect}s
first_byte: %{time_starttransfer}s
total: %{time_total}s
' \
  "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @chat-request.json

تفسیر

time_namelookup: زمان DNS
time_connect: زمان اتصال TCP
time_appconnect: زمان TLS
time_starttransfer: زمان تا دریافت اولین Byte
time_total: زمان کل

در پاسخ غیرStreaming، time_starttransfer الزاماً معادل Time to First Token مدل نیست؛ زیرا ممکن است Server پس از تکمیل پردازش شروع به ارسال پاسخ کند.

حالت Verbose

برای Debug اتصال:

curl -v "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

Verbose اطلاعاتی مانند این موارد را نشان می‌دهد:

DNS
اتصال
TLS
Request Headers
Response Headers

هشدار امنیتی

خروجی Verbose ممکن است Authorization Header را نمایش دهد. آن را:

Screenshot نگیرید؛
در Issue عمومی قرار ندهید؛
بدون پاک‌سازی برای پشتیبانی نفرستید؛
در Log دائمی ذخیره نکنید.

تست Streaming

فایل stream-request.json:

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "Context Window را کامل توضیح بده."
    }
  ],
  "stream": true,
  "max_tokens": 1000
}

اجرا:

curl --no-buffer \
  "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @stream-request.json

گزینه --no-buffer باعث می‌شود cURL داده خروجی را Buffer نکند و Chunkها سریع‌تر در Terminal دیده شوند.

فرم کوتاه آن:

-N

curl -N ...

ساختار Streaming

خروجی رابط سازگار ممکن است شبیه این باشد:

data: {"choices":[{"delta":{"role":"assistant"}}]}

data: {"choices":[{"delta":{"content":"Context"}}]}

data: {"choices":[{"delta":{"content":" Window"}}]}

data: [DONE]

این خروجی یک JSON واحد نیست. هر خط data: یک رویداد یا Chunk جداست.

Streaming در PowerShell

curl.exe --no-buffer `
  "$env:DARVAREH_BASE_URL/chat/completions" `
  -H "Authorization: Bearer $env:DARVAREH_API_KEY" `
  -H "Content-Type: application/json" `
  --data-binary "@stream-request.json"

Usage در Streaming

در مدل‌ها و مسیرهای پشتیبانی‌شده:

{
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}

Usage ممکن است در Chunk نهایی برگردد. اگر Stream قطع شود، دریافت Chunk نهایی تضمین‌شده نیست.

استخراج متن از SSE

برای Debug ساده در Linux و macOS:

curl -sS -N \
  "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @stream-request.json |
while IFS= read -r line; do
  case "$line" in
    "data: [DONE]")
      break
      ;;
    data:\ *)
      payload="${line#data: }"
      printf '%s' "$payload" |
      jq -rj '.choices[0].delta.content // empty'
      ;;
  esac
done

printf '\n'

این Script فقط برای ساختار رایج Chat Completions است. Eventهای Endpointها و مدل‌های مختلف ممکن است ساختار متفاوتی داشته باشند.

لغو درخواست Streaming

در Terminal معمولاً با این کلیدها درخواست متوقف می‌شود:

Ctrl + C

قطع Client الزاماً به این معنا نیست که Provider همان لحظه تولید را متوقف کرده یا هیچ هزینه‌ای ثبت نمی‌شود. رفتار لغو و Usage به مسیر و Provider وابسته است.

ارسال تصویر با URL

مدل باید Vision یا Image Input را پشتیبانی کند.

فایل vision-url.json:

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "این تصویر را به زبان فارسی توضیح بده."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.jpg"
          }
        }
      ]
    }
  ],
  "max_tokens": 700
}

ارسال:

curl -sS "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @vision-url.json |
jq -r '.choices[0].message.content'

شرایط URL تصویر

از اینترنت قابل‌دسترسی باشد.
بهتر است HTTPS باشد.
به Login نیاز نداشته باشد.
پیش از پردازش منقضی نشود.
فرمت آن توسط مدل پشتیبانی شود.
حجم آن از محدودیت مدل عبور نکند.

آدرس‌هایی مانند موارد زیر برای Provider خارجی قابل‌دسترسی نیستند:

http://localhost/image.jpg

file:///home/user/image.jpg

ارسال تصویر Base64

برای تصویر Local می‌توان Data URL ساخت.

Linux

IMAGE_BASE64=$(base64 -w 0 image.jpg)

در macOS گزینه -w ممکن است وجود نداشته باشد:

IMAGE_BASE64=$(base64 < image.jpg | tr -d '\n')

ساخت Body با jq

jq -n \
  --arg model "$DARVAREH_MODEL" \
  --arg image "$IMAGE_BASE64" \
  '{
    model: $model,
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: "این تصویر را توضیح بده."
          },
          {
            type: "image_url",
            image_url: {
              url: ("data:image/jpeg;base64," + $image)
            }
          }
        ]
      }
    ],
    max_tokens: 700
  }' > vision-base64.json

ارسال:

curl -sS "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @vision-base64.json |
jq -r '.choices[0].message.content'

PowerShell

$imageBase64 = [Convert]::ToBase64String(
  [IO.File]::ReadAllBytes("image.jpg")
)

$dataUrl = "data:image/jpeg;base64,$imageBase64"

$bodyObject = @{
  model = $env:DARVAREH_MODEL
  messages = @(
    @{
      role = "user"
      content = @(
        @{
          type = "text"
          text = "این تصویر را توضیح بده."
        },
        @{
          type = "image_url"
          image_url = @{
            url = $dataUrl
          }
        }
      )
    }
  )
  max_tokens = 700
}

$bodyObject |
  ConvertTo-Json -Depth 10 |
  Set-Content -Encoding utf8 vision-base64.json

ارسال:

curl.exe -sS `
  "$env:DARVAREH_BASE_URL/chat/completions" `
  -H "Authorization: Bearer $env:DARVAREH_API_KEY" `
  -H "Content-Type: application/json" `
  --data-binary "@vision-base64.json"

نکات Base64

حجم داده افزایش پیدا می‌کند.
فایل JSON نهایی می‌تواند بسیار بزرگ شود.
فایل ممکن است حاوی اطلاعات حساس باشد.
MIME Type باید درست باشد.
برای PNG از image/png استفاده کنید.
برای تصویر عمومی، URL مستقیم معمولاً بهینه‌تر است.

ارسال چند تصویر

در مدل‌های پشتیبانی‌شده:

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "این دو تصویر را مقایسه کن."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/first.jpg"
          }
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/second.jpg"
          }
        }
      ]
    }
  ]
}

محدودیت تعداد و حجم تصاویر به مدل و Provider وابسته است.

JSON Mode

فایل json-mode.json:

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "اطلاعات را فقط به‌صورت JSON معتبر برگردان."
    },
    {
      "role": "user",
      "content": "محصول: هدفون بی‌سیم مدل X، رنگ مشکی، قیمت ۴۵۰۰۰۰۰ تومان"
    }
  ],
  "response_format": {
    "type": "json_object"
  },
  "temperature": 0
}

ارسال:

curl -sS "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @json-mode.json |
jq -r '.choices[0].message.content' |
jq

دو مرحله jq:

محتوای String از پاسخ اصلی استخراج می‌شود.
String به‌عنوان JSON جدید Parse می‌شود.

محدودیت JSON Mode

JSON Mode معمولاً معتبر‌بودن Syntax را هدف قرار می‌دهد، اما ساختار دقیق فیلدها را تضمین نمی‌کند.

مدل ممکن است این خروجی معتبر را بدهد:

{
  "product_name": "هدفون X",
  "price": "4500000"
}

درحالی‌که برنامه انتظار دارد:

{
  "name": "هدفون X",
  "price_toman": 4500000
}

برای قرارداد دقیق‌تر از Structured Outputs استفاده کنید.

Structured Outputs

فایل structured-output.json:

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "اطلاعات محصول را بدون حدس‌زدن استخراج کن."
    },
    {
      "role": "user",
      "content": "هدفون بی‌سیم مدل X، رنگ مشکی، قیمت ۴۵۰۰۰۰۰ تومان و دارای حذف نویز فعال"
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "product_information",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "color": {
            "type": [
              "string",
              "null"
            ]
          },
          "price_toman": {
            "type": [
              "number",
              "null"
            ]
          },
          "features": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "name",
          "color",
          "price_toman",
          "features"
        ],
        "additionalProperties": false
      }
    }
  },
  "temperature": 0
}

ارسال و Parse:

curl -sS "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @structured-output.json |
jq -r '.choices[0].message.content' |
jq

اعتبارسنجی فیلدها با jq

RESULT=$(
  curl -sS "$DARVAREH_BASE_URL/chat/completions" \
    -H "Authorization: Bearer $DARVAREH_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @structured-output.json |
  jq -r '.choices[0].message.content'
)

printf '%s' "$RESULT" |
jq -e '
  has("name")
  and has("color")
  and has("price_toman")
  and has("features")
  and (.features | type == "array")
'

گزینه -e باعث می‌شود jq براساس نتیجه Filter، Exit Code مناسب برگرداند و برای Script و CI مفید است.

پشتیبانی مدل

همه مدل‌ها از این قابلیت‌ها پشتیبانی نمی‌کنند:

response_format
json_schema
strict

اگر خطای 400 دریافت کردید:

مدل دیگری انتخاب کنید.
قابلیت مدل را بررسی کنید.
JSON Mode را آزمایش کنید.
Schema را ساده‌تر کنید.
پارامتر ناسازگار را حذف کنید.

تست Tool Calling

فایل tool-call.json:

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "وضعیت سفارش ORD-2048 را بررسی کن."
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "دریافت وضعیت سفارش با شناسه سفارش",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string",
              "description": "شناسه سفارش مانند ORD-2048"
            }
          },
          "required": [
            "order_id"
          ],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "auto"
}

ارسال:

curl -sS "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @tool-call.json |
jq

خروجی احتمالی:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_example",
            "type": "function",
            "function": {
              "name": "get_order_status",
              "arguments": "{\"order_id\":\"ORD-2048\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

استخراج نام Tool

... | jq -r \
  '.choices[0].message.tool_calls[0].function.name'

استخراج آرگومان‌ها

... | jq -r \
  '.choices[0].message.tool_calls[0].function.arguments' |
jq

فیلد arguments معمولاً یک String شامل JSON است، بنابراین دوباره Parse می‌شود.

ذخیره Tool Call

curl -sS "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @tool-call.json \
  -o tool-response.json

Tool Call ID:

TOOL_CALL_ID=$(
  jq -r \
    '.choices[0].message.tool_calls[0].id' \
    tool-response.json
)

آرگومان سفارش:

ORDER_ID=$(
  jq -r \
    '.choices[0].message.tool_calls[0].function.arguments' \
    tool-response.json |
  jq -r '.order_id'
)

مدل Tool را اجرا نمی‌کند

مدل فقط پیشنهاد می‌دهد تابعی با آرگومان مشخص اجرا شود. برنامه شما باید:

نام Tool را با Allowlist بررسی کند.
آرگومان‌ها را Parse کند.
Schema را Validate کند.
مجوز کاربر را بررسی کند.
تابع واقعی را اجرا کند.
نتیجه را به مدل برگرداند.
پاسخ نهایی را دریافت کند.

هرگز Tool Call مدل را بدون Validation مستقیماً اجرا نکنید.

ارسال نتیجه Tool به مدل

فرض کنید نتیجه واقعی ابزار چنین است:

{
  "order_id": "ORD-2048",
  "status": "shipped",
  "tracking_code": "TR-5521"
}

فایل tool-result.json:

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "وضعیت سفارش ORD-2048 را بررسی کن."
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_example",
          "type": "function",
          "function": {
            "name": "get_order_status",
            "arguments": "{\"order_id\":\"ORD-2048\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_example",
      "content": "{\"order_id\":\"ORD-2048\",\"status\":\"shipped\",\"tracking_code\":\"TR-5521\"}"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "دریافت وضعیت سفارش",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string"
            }
          },
          "required": [
            "order_id"
          ],
          "additionalProperties": false
        }
      }
    }
  ]
}

ارسال:

curl -sS "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @tool-result.json |
jq -r '.choices[0].message.content'

ساختار Tool Calling می‌تواند میان مدل‌ها و APIهای بومی متفاوت باشد. این نمونه براساس رابط رایج Chat Completions سازگار با OpenAI است.

تولید تصویر با cURL

اگر مدل و مسیر انتخابی درواره از Endpoint سازگار تولید تصویر پشتیبانی کنند، Endpoint رایج می‌تواند چنین باشد:

POST /images/generations

فایل image-generation.json:

{
  "model": "IMAGE_MODEL_ID",
  "prompt": "A minimal futuristic AI gateway, dark navy and purple, enterprise style",
  "size": "1024x1024",
  "n": 1
}

درخواست:

curl -sS "$DARVAREH_BASE_URL/images/generations" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @image-generation.json |
jq

تفاوت مدل‌های تصویری

پارامترهای مدل‌ها ممکن است متفاوت باشند:

size
width
height
aspect_ratio
quality
n
output_format
response_format
seed

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

دانلود تصویر خروجی URL

اگر پاسخ دارای URL باشد:

IMAGE_URL=$(
  jq -r '.data[0].url' image-response.json
)

دانلود:

curl -L "$IMAGE_URL" -o generated-image.png

گزینه -L Redirectها را دنبال می‌کند.

URLهای موقت

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

دریافت خروجی Base64 تصویر

اگر Response شامل Base64 باشد:

jq -r '.data[0].b64_json' image-response.json |
base64 --decode > generated-image.png

در macOS ممکن است از این گزینه استفاده شود:

base64 -D

در PowerShell:

$response = Get-Content image-response.json |
  ConvertFrom-Json

$bytes = [Convert]::FromBase64String(
  $response.data[0].b64_json
)

[IO.File]::WriteAllBytes(
  "generated-image.png",
  $bytes
)

نام فیلد و فرمت پاسخ به مدل و Endpoint بستگی دارد.

Timeout اتصال

curl --connect-timeout 5 \
  "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

این گزینه حداکثر زمان مرحله اتصال را تعیین می‌کند.

Timeout کل

curl --max-time 60 \
  "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @chat-request.json

معادل کوتاه:

-m 60

ترکیب Timeoutها

curl \
  --connect-timeout 5 \
  --max-time 60 \
  "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @chat-request.json

برای مدل‌های Reasoning، تصویر یا ویدئو ممکن است Deadline طولانی‌تری نیاز باشد. وظایف بسیار طولانی بهتر است با Job غیرهم‌زمان اجرا شوند.

Fail روی HTTP Error

cURL به‌صورت پیش‌فرض ممکن است حتی برای HTTP 400 یا 500 Exit Code موفق برگرداند، چون انتقال HTTP انجام شده است.

گزینه پیشنهادی:

--fail-with-body

curl --fail-with-body \
  "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

این گزینه برای Statusهای خطا، Exit Code غیرصفر ایجاد می‌کند و Body خطا را نیز نگه می‌دارد.

برای Script:

if ! curl -sS --fail-with-body \
  "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -o models.json; then
  echo "API request failed" >&2
  exit 1
fi

Retry با cURL

curl \
  --retry 3 \
  --retry-delay 2 \
  --retry-max-time 20 \
  "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

گزینه‌ها

--retry 3: حداکثر سه Retry
--retry-delay 2: فاصله ثابت دو ثانیه
--retry-max-time 20: سقف زمان Retry

Retry برای خطاهای بیشتر

نسخه‌های جدید cURL گزینه زیر را دارند:

--retry-all-errors

اما استفاده از آن باید با احتیاط باشد:

curl \
  --retry 3 \
  --retry-all-errors \
  --retry-max-time 30 \
  ...

خطر Retry

Retry برای همه درخواست‌ها امن نیست. اگر Endpoint عملیاتی تغییردهنده انجام دهد، اجرای دوباره ممکن است اثر را تکرار کند.

برای Chat Completion، Retry ممکن است:

هزینه مجدد ایجاد کند؛
پاسخ دیگری تولید کند؛
درخواست قبلی را که وضعیتش نامعلوم است دوباره اجرا کند.

برای عملیات حساس از Idempotency استفاده کنید و Retry را محدود نگه دارید.

فرمان مقاوم پیشنهادی

curl -sS \
  --fail-with-body \
  --connect-timeout 5 \
  --max-time 60 \
  --retry 2 \
  --retry-max-time 20 \
  "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @chat-request.json

دقت کنید مجموع رفتار Timeout و Retry باید با Deadline کلی برنامه سازگار باشد.

مدیریت خطای 400

400 Bad Request معمولاً نشان‌دهنده مشکل در Request است:

JSON نامعتبر
مدل اشتباه
پارامتر ناسازگار
messages نامعتبر
Context بزرگ
JSON Schema نامعتبر
URL تصویر نامعتبر

بررسی JSON:

jq empty request.json

مشاهده Body خطا:

curl -sS --fail-with-body ...

Retry با همان درخواست معمولاً این خطا را حل نمی‌کند.

مدیریت خطای 401

401 Unauthorized معمولاً مربوط به API Key است.

بررسی کنید:

Variable مقدار دارد.
کلید کامل است.
کلید Revoke نشده است.
Header درست نوشته شده است.
قبل یا بعد کلید Space اضافی نیست.
کلمه Bearer دوبار تکرار نشده است.

بررسی وجود Variable بدون نمایش مقدار:

if [ -z "${DARVAREH_API_KEY:-}" ]; then
  echo "DARVAREH_API_KEY is not set" >&2
  exit 1
fi

در PowerShell:

if (-not $env:DARVAREH_API_KEY) {
  throw "DARVAREH_API_KEY is not set"
}

مدیریت خطای 403

این خطا می‌تواند نشان‌دهنده عدم مجوز، وضعیت حساب یا محدودیت دسترسی باشد.

برای گزارش مشکل این موارد را ثبت کنید:

زمان درخواست
Endpoint
مدل
HTTP Status
Request ID
Body خطای پاک‌سازی‌شده

API Key را برای پشتیبانی ارسال نکنید.

مدیریت خطاهای Billing و موجودی

اگر اعتبار کافی نباشد، درخواست ممکن است پیش از تماس با Provider رد شود.

در این حالت:

موجودی را بررسی کنید.
قیمت مدل را در نظر بگیرید.
max_tokens را منطقی کنید.
Retry خودکار انجام ندهید.
error.code و Status واقعی را ثبت کنید.

کد HTTP و ساختار دقیق خطا باید براساس قرارداد فعلی API درواره بررسی شود.

مدیریت خطای 404

دلایل:

Base URL اشتباه
حذف /v1
Endpoint اشتباه
شناسه مدل اشتباه
Method اشتباه

Base URL صحیح:

https://api.darvareh.ir/v1

مدیریت خطای 429

دلایل احتمالی:

RPM
TPM
Concurrency
Quota
Burst

Headerها را بررسی کنید:

curl -i ...

اگر Retry-After وجود دارد، آن را رعایت کنید.

راهکارها:

فاصله میان درخواست‌ها
کاهش Concurrency
کاهش Context
کاهش max_tokens
حذف درخواست‌های تکراری
Retry محدود با Backoff

مدیریت خطاهای 5xx

کدهای 500، 502، 503 و 504 معمولاً می‌توانند موقت باشند.

اقدامات:

Request ID را ذخیره کنید.
Retry محدود انجام دهید.
زمان و مدل را ثبت کنید.
وضعیت Provider را بررسی کنید.
مدل جایگزین سازگار را آزمایش کنید.
از Retry نامحدود خودداری کنید.

دریافت Exit Code cURL

پس از اجرا در Bash:

echo $?

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

با --fail-with-body خطاهای HTTP نیز Exit Code غیرصفر ایجاد می‌کنند.

در PowerShell:

$LASTEXITCODE

فایل تنظیمات cURL

می‌توانید گزینه‌های تکراری را در فایل Config قرار دهید.

فایل:

darvareh.curlrc

محتوا:

silent
show-error
fail-with-body
connect-timeout = 5
max-time = 60
header = "Content-Type: application/json"

استفاده:

curl --config darvareh.curlrc \
  "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  --data-binary @chat-request.json

API Key را در فایل Config اشتراکی قرار ندهید

فایل Config ممکن است:

وارد Git شود؛
Backup شود؛
به اشتراک گذاشته شود؛
توسط کاربران دیگر خوانده شود.

Secret را جدا نگه دارید و Permission فایل را بررسی کنید.

استفاده از `.netrc`

cURL از .netrc برای Credentialهای بعضی روش‌های احراز هویت پشتیبانی می‌کند، اما Bearer Token معمولاً بهتر است با Header و Secret Manager مدیریت شود. قراردادن Bearer Token در فایل‌های Credential بدون طراحی مناسب می‌تواند خطر امنیتی داشته باشد.

برای API درواره، متغیر محیطی یا Secret Manager گزینه روشن‌تری است.

ساخت Script Bash آماده

فایل:

darvareh-chat.sh

محتوا:

#!/usr/bin/env bash

set -euo pipefail

: "${DARVAREH_API_KEY:?DARVAREH_API_KEY is required}"
: "${DARVAREH_MODEL:?DARVAREH_MODEL is required}"

DARVAREH_BASE_URL="${DARVAREH_BASE_URL:-https://api.darvareh.ir/v1}"

PROMPT="${1:-هوش مصنوعی چیست؟}"

BODY=$(
  jq -n \
    --arg model "$DARVAREH_MODEL" \
    --arg prompt "$PROMPT" \
    '{
      model: $model,
      messages: [
        {
          role: "user",
          content: $prompt
        }
      ],
      temperature: 0.2,
      max_tokens: 700
    }'
)

RESPONSE=$(
  printf '%s' "$BODY" |
  curl -sS \
    --fail-with-body \
    --connect-timeout 5 \
    --max-time 60 \
    "$DARVAREH_BASE_URL/chat/completions" \
    -H "Authorization: Bearer $DARVAREH_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @-
)

printf '%s\n' "$RESPONSE" |
jq -r '.choices[0].message.content'

اجرایی‌کردن:

chmod +x darvareh-chat.sh

اجرا:

./darvareh-chat.sh "RAG چیست؟"

نکته امنیتی

Script نباید API Key ثابت داشته باشد. Secret از Environment دریافت می‌شود.

Script PowerShell آماده

فایل:

darvareh-chat.ps1

محتوا:

param(
  [Parameter(Mandatory = $true)]
  [string]$Prompt
)

if (-not $env:DARVAREH_API_KEY) {
  throw "DARVAREH_API_KEY is required"
}

if (-not $env:DARVAREH_MODEL) {
  throw "DARVAREH_MODEL is required"
}

$baseUrl = if ($env:DARVAREH_BASE_URL) {
  $env:DARVAREH_BASE_URL
} else {
  "https://api.darvareh.ir/v1"
}

$bodyObject = @{
  model = $env:DARVAREH_MODEL
  messages = @(
    @{
      role = "user"
      content = $Prompt
    }
  )
  temperature = 0.2
  max_tokens = 700
}

$body = $bodyObject | ConvertTo-Json -Depth 10

$response = curl.exe -sS `
  --fail-with-body `
  --connect-timeout 5 `
  --max-time 60 `
  "$baseUrl/chat/completions" `
  -H "Authorization: Bearer $env:DARVAREH_API_KEY" `
  -H "Content-Type: application/json" `
  --data-raw $body

if ($LASTEXITCODE -ne 0) {
  throw "API request failed"
}

$json = $response | ConvertFrom-Json
$json.choices[0].message.content

اجرا:

.\darvareh-chat.ps1 -Prompt "RAG چیست؟"

اجرای چند Prompt از فایل

فایل prompts.txt:

API چیست؟
RAG چیست؟
Context Window چیست؟

Script:

while IFS= read -r prompt; do
  [ -z "$prompt" ] && continue

  echo "Prompt: $prompt"

  ./darvareh-chat.sh "$prompt"

  sleep 2
done < prompts.txt

نکته هزینه و Rate Limit

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

تعداد Promptها را بررسی کنید.
max_tokens را کاهش دهید.
فاصله درخواست‌ها را تنظیم کنید.
ابتدا چند نمونه آزمایش کنید.
هزینه مدل را در نظر بگیرید.

اجرای درخواست‌ها به‌صورت موازی

ابزارهایی مانند xargs -P می‌توانند درخواست‌ها را موازی کنند، اما این کار ممکن است:

Rate Limit را پر کند؛
هزینه را ناگهان افزایش دهد؛
Concurrency را اشغال کند؛
Debug را دشوار کند.

برای شروع از اجرای ترتیبی استفاده کنید. پردازش موازی باید با محدودیت مشخص انجام شود.

ذخیره Response و Metadata

یک الگوی ساده:

TIMESTAMP=$(date -u +"%Y%m%dT%H%M%SZ")
OUTPUT_DIR="outputs/$TIMESTAMP"

mkdir -p "$OUTPUT_DIR"

curl -sS \
  -D "$OUTPUT_DIR/headers.txt" \
  -o "$OUTPUT_DIR/response.json" \
  -w "%{http_code}\n%{time_total}\n" \
  "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @chat-request.json \
  > "$OUTPUT_DIR/metrics.txt"

هشدار

Response ممکن است حاوی داده حساس باشد. Retention، Permission و محل ذخیره را کنترل کنید.

تبدیل cURL به Postman

در Postman:

روی Import کلیک کنید.
Raw Text را انتخاب کنید.
فرمان cURL را Paste کنید.
Request را Import کنید.
API Key را با Vault یا Variable امن جایگزین کنید.
Request را در Collection ذخیره کنید.

قبل از Pasteکردن cURL در ابزارهای آنلاین، Secret را حذف کنید.

تبدیل Request Postman به cURL

Postman می‌تواند از یک Request، Code Snippet cURL تولید کند.

پس از دریافت فرمان:

API Key را حذف کنید.
URL خصوصی را بررسی کنید.
داده حساس را پاک کنید.
Syntax مربوط به Shell مقصد را انتخاب کنید.

تبدیل cURL به Python

نمونه cURL:

curl "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @chat-request.json

نمونه Python با SDK سازگار:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DARVAREH_API_KEY"],
    base_url="https://api.darvareh.ir/v1",
)

response = client.chat.completions.create(
    model=os.environ["DARVAREH_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "API چیست؟",
        }
    ],
)

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

تبدیل cURL به JavaScript

const response = await fetch(
  "https://api.darvareh.ir/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization:
        `Bearer ${process.env.DARVAREH_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: process.env.DARVAREH_MODEL,
      messages: [
        {
          role: "user",
          content: "API چیست؟",
        },
      ],
    }),
  },
);

if (!response.ok) {
  throw new Error(
    `API request failed: ${response.status}`,
  );
}

const data = await response.json();

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

cURL و Proxy

اگر سرور شما از Proxy استفاده می‌کند، cURL می‌تواند متغیرهای محیطی Proxy را در نظر بگیرد:

HTTP_PROXY
HTTPS_PROXY
NO_PROXY

نمایش:

env | grep -i proxy

Proxy می‌تواند روی موارد زیر اثر بگذارد:

اتصال
TLS
Latency
Streaming
محدودیت اندازه Body
ثبت داده

در سازمان‌ها سیاست Proxy و حریم خصوصی را بررسی کنید.

مشکل Certificate

از گزینه زیر برای دورزدن بررسی TLS استفاده نکنید:

-k

یا:

--insecure

این گزینه اعتبار Certificate را بررسی نمی‌کند و خطر حمله Man-in-the-Middle ایجاد می‌کند.

اگر خطای Certificate دارید:

ساعت سیستم را بررسی کنید.
CA Bundle را به‌روزرسانی کنید.
Proxy سازمانی را بررسی کنید.
Certificate Chain را بررسی کنید.
از مدیر سیستم کمک بگیرید.

غیرفعال‌کردن TLS Verification راه‌حل Production نیست.

مشکل Encoding فارسی در Windows

اگر متن فارسی خراب نمایش داده می‌شود:

PowerShell

Encoding Terminal را روی UTF-8 تنظیم کنید:

[Console]::OutputEncoding =
  [System.Text.Encoding]::UTF8

برای فایل:

Set-Content -Encoding utf8 request.json

نسخه‌های جدید PowerShell مدیریت UTF-8 بهتری دارند. Microsoft اشاره می‌کند که در PowerShell 7.4 به بعد Encoding درخواست‌ها به‌صورت پیش‌فرض UTF-8 است. مستندات Invoke-WebRequest

برای cURL، Header زیر نیز مناسب است:

Content-Type: application/json; charset=utf-8

-H "Content-Type: application/json; charset=utf-8"

Shell History و API Key

اگر قبلاً API Key را مستقیماً در فرمان نوشته‌اید، ممکن است در History ذخیره شده باشد.

Bash:

history

PowerShell:

Get-History

حذف یک فرمان از History همیشه تمام نسخه‌های ذخیره‌شده را از Disk یا ابزارهای دیگر پاک نمی‌کند.

اگر احتمال افشای API Key وجود دارد:

کلید را Revoke کنید.
کلید جدید بسازید.
Usage را بررسی کنید.
فایل‌ها و Logها را پاک‌سازی کنید.
از متغیر محیطی یا Secret Manager استفاده کنید.

فقط پاک‌کردن خط از History جایگزین Rotation کلید نیست.

Process List و Secret

در بعضی سیستم‌ها Argumentهای فرمان می‌توانند توسط کاربران یا ابزارهای دیگر دیده شوند. به همین دلیل قراردادن Secret مستقیم در Argument مناسب نیست.

این فرمان خطر بیشتری دارد:

curl -H "Authorization: Bearer REAL_SECRET" ...

استفاده از متغیر محیطی نمایش مستقیم را کاهش می‌دهد، اما برای محیط‌های حساس Secret Manager و Credential Injection مناسب‌تر است.

Git و فایل‌های درخواست

اگر فایل‌ها حاوی اطلاعات خصوصی‌اند، آن‌ها را به .gitignore اضافه کنید:

.env
*.secret.json
vision-base64.json
response.json
outputs/

اما اگر Secret قبلاً Commit شده است، افزودن آن به .gitignore کافی نیست. باید:

کلید را Revoke کنید؛
تاریخچه Repository را در صورت نیاز پاک‌سازی کنید؛
دسترسی‌ها را بررسی کنید.

استفاده از `.env`

فایل .env:

DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_BASE_URL=https://api.darvareh.ir/v1
DARVAREH_MODEL=MODEL_ID

Bash ساده به‌صورت پیش‌فرض .env را خودکار بارگذاری نمی‌کند. یکی از روش‌ها:

set -a
source .env
set +a

فایل .env را در Git قرار ندهید:

.env

نکته امنیتی

فرمت .env برای توسعه محلی مفید است، اما در Production بهتر است از Secret Manager یا سیستم مدیریت Secret زیرساخت استفاده شود.

اجرای cURL در Docker

اگر Image دارای cURL باشد:

docker run --rm \
  -e DARVAREH_API_KEY \
  curlimages/curl:latest \
  -sS \
  https://api.darvareh.ir/v1/models \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

انتقال Environment به Container باید با سیاست امنیتی شما سازگار باشد. Secret را داخل Dockerfile یا Image قرار ندهید.

استفاده در CI/CD

برای Smoke Test می‌توان از cURL استفاده کرد:

curl -sS \
  --fail-with-body \
  --connect-timeout 5 \
  --max-time 30 \
  "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -o models.json

jq -e '.data | type == "array"' models.json

نکات CI

API Key را در Secret Store پلتفرم CI قرار دهید.
Secret را در Log چاپ نکنید.
set -x را برای فرمان‌های حاوی Secret فعال نکنید.
هزینه Test را محدود کنید.
مدل و Prompt تست را ثابت نگه دارید.
Testهای بزرگ را روی هر Commit اجرا نکنید.

بررسی Response Contract در Script

RESPONSE_FILE=$(mktemp)

cleanup() {
  rm -f "$RESPONSE_FILE"
}

trap cleanup EXIT

curl -sS \
  --fail-with-body \
  "$DARVAREH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @chat-request.json \
  -o "$RESPONSE_FILE"

jq -e '
  (.choices | type == "array")
  and (.choices | length > 0)
  and (.choices[0].message.content | type == "string")
' "$RESPONSE_FILE"

این Test ساختار را بررسی می‌کند، نه صحت معنایی پاسخ.

تست زمان پاسخ در Script

TOTAL_TIME=$(
  curl -sS \
    -o response.json \
    -w "%{time_total}" \
    "$DARVAREH_BASE_URL/chat/completions" \
    -H "Authorization: Bearer $DARVAREH_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @chat-request.json
)

echo "Total time: $TOTAL_TIME seconds"

برای مقایسه عددی Decimal می‌توانید از awk استفاده کنید:

awk -v time="$TOTAL_TIME" '
BEGIN {
  if (time > 30) {
    print "Response was too slow"
    exit 1
  }
}
'

تست چند مدل

فایل models.txt:

MODEL_A
MODEL_B
MODEL_C

Script:

while IFS= read -r model; do
  [ -z "$model" ] && continue

  jq \
    --arg model "$model" \
    '.model = $model' \
    chat-request.json \
    > current-request.json

  echo "Testing: $model"

  curl -sS \
    --fail-with-body \
    "$DARVAREH_BASE_URL/chat/completions" \
    -H "Authorization: Bearer $DARVAREH_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @current-request.json |
  jq '{
    model: .model,
    usage: .usage,
    finish_reason: .choices[0].finish_reason,
    content: .choices[0].message.content
  }'

  sleep 2
done < models.txt

rm -f current-request.json

مقایسه درست مدل‌ها

یک بار اجرای هر مدل کافی نیست. برای ارزیابی بهتر:

Dataset واقعی داشته باشید.
چند نمونه اجرا کنید.
هزینه را ثبت کنید.
Latency را اندازه بگیرید.
خروجی را با Rubric ارزیابی کنید.
Structured Output Validation را بررسی کنید.
تفاوت قابلیت مدل‌ها را در نظر بگیرید.

خطاهای رایج

استفاده از `curl` در PowerShell 5.1

ممکن است Invoke-WebRequest اجرا شود. از این دستور استفاده کنید:

curl.exe

فراموش‌کردن `/v1`

صحیح:

https://api.darvareh.ir/v1

تکرار Endpoint

اگر Base URL تا /chat/completions تنظیم شود و دوباره Endpoint اضافه کنید، URL خراب می‌شود. Base URL باید تا /v1 باشد.

تکرار کلمه Bearer

اشتباه:

export DARVAREH_API_KEY="Bearer YOUR_KEY"

سپس:

-H "Authorization: Bearer $DARVAREH_API_KEY"

نتیجه:

Bearer Bearer YOUR_KEY

Variable باید فقط خود کلید باشد.

نقل‌قول اشتباه در Shell

JSON طولانی را در فایل قرار دهید یا با jq بسازید.

ارسال مدل ناسازگار

مدل Text-only نمی‌تواند تصویر را تحلیل کند. همه مدل‌ها Tools یا Structured Outputs ندارند.

Parseکردن SSE به‌عنوان JSON واحد

Streaming مجموعه‌ای از Eventهاست، نه یک Object JSON واحد.

استفاده از `--insecure`

بررسی TLS را غیرفعال می‌کند و نباید راه‌حل Production باشد.

Retry نامحدود

هزینه و فشار سیستم را افزایش می‌دهد.

چاپ API Key در Verbose Log

خروجی -v را پیش از اشتراک پاک‌سازی کنید.

اجرای Batch بدون برآورد هزینه

هر درخواست ممکن است هزینه واقعی ایجاد کند.

چک‌لیست استفاده از API درواره با cURL

آماده‌سازی

cURL نصب است.
نسخه آن با curl --version بررسی شده است.
در Windows از curl.exe استفاده می‌شود.
jq در صورت نیاز نصب شده است.
حساب و API Key درواره آماده‌اند.
شناسه مدل معتبر انتخاب شده است.

تنظیمات

Base URL برابر https://api.darvareh.ir/v1 است.
API Key در Environment یا Secret Manager قرار دارد.
API Key داخل Git نیست.
API Key شامل کلمه Bearer نیست.
مدل در Variable جداگانه ذخیره شده است.

Request

Endpoint صحیح است.
Method صحیح است.
Authorization Header وجود دارد.
Content-Type برابر application/json است.
Body، JSON معتبر است.
model مقدار دارد.
messages ساختار صحیح دارد.
max_tokens منطقی است.

Streaming

مدل Streaming را پشتیبانی می‌کند.
stream برابر true است.
از --no-buffer استفاده می‌شود.
SSE به‌عنوان JSON واحد Parse نمی‌شود.
احتمال ناقص‌ماندن Stream در نظر گرفته شده است.

Vision

مدل از Image Input پشتیبانی می‌کند.
URL تصویر عمومی و امن است.
MIME Type Base64 درست است.
فایل Base64 وارد Git نمی‌شود.
اندازه Request محدود است.

Structured Outputs

مدل از json_schema پشتیبانی می‌کند.
Schema معتبر است.
خروجی داخلی دوباره Parse می‌شود.
ساختار با Validator بررسی می‌شود.
خطای Validation مدیریت می‌شود.

Tool Calling

مدل از Tools پشتیبانی می‌کند.
نام Tool با Allowlist بررسی می‌شود.
Arguments Parse و Validate می‌شوند.
Tool در Backend اجرا می‌شود.
مجوز کاربر مستقل بررسی می‌شود.
عملیات حساس تأیید انسانی دارد.

پایداری

Connection Timeout تنظیم شده است.
Max Time مشخص است.
از --fail-with-body استفاده می‌شود.
Retry محدود است.
429 با فاصله مناسب مدیریت می‌شود.
400 بدون تغییر درخواست Retry نمی‌شود.
Status و Body خطا ثبت می‌شوند.

امنیت

Secret در Command ثابت نوشته نشده است.
Verbose Log پاک‌سازی می‌شود.
Shell History بررسی شده است.
فایل .env در Git نیست.
فایل Response حساس محافظت می‌شود.
Certificate Verification غیرفعال نشده است.
در صورت افشای کلید، Rotation انجام می‌شود.

پرسش‌های متداول

cURL چیست؟

cURL یک ابزار خط فرمان برای ارسال و دریافت داده با استفاده از URL است و برای آزمایش HTTP APIها کاربرد گسترده‌ای دارد.

Base URL درواره چیست؟

https://api.darvareh.ir/v1

چگونه API Key را ارسال کنیم؟

با Authorization Header:

-H "Authorization: Bearer $DARVAREH_API_KEY"

چگونه فهرست مدل‌ها را دریافت کنیم؟

curl "$DARVAREH_BASE_URL/models" \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

چگونه Chat Completion ارسال کنیم؟

یک درخواست POST به این Endpoint ارسال کنید:

/v1/chat/completions

Body باید حداقل شامل model و messages باشد.

چرا در PowerShell فرمان cURL کار نمی‌کند؟

در Windows PowerShell 5.1، curl ممکن است Alias مربوط به Invoke-WebRequest باشد. از curl.exe استفاده کنید.

jq چیست؟

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

چگونه فقط متن مدل را نمایش دهیم؟

... | jq -r '.choices[0].message.content'

چگونه Streaming را تست کنیم؟

در Body مقدار stream را true قرار دهید و cURL را با --no-buffer اجرا کنید:

curl --no-buffer ...

آیا می‌توان تصویر Local ارسال کرد؟

در مدل‌های پشتیبانی‌شده می‌توانید تصویر را Base64 و در قالب Data URL ارسال کنید. برای تصویر عمومی، URL مستقیم معمولاً ساده‌تر است.

تفاوت JSON Mode و Structured Outputs چیست؟

JSON Mode معتبر‌بودن JSON را هدف قرار می‌دهد، اما Structured Outputs ساختار مشخص‌شده با JSON Schema را نیز اعمال می‌کند. مدل باید از قابلیت موردنظر پشتیبانی کند.

آیا cURL می‌تواند Tool را اجرا کند؟

cURL فقط Request را ارسال می‌کند. مدل نیز فقط Tool Call پیشنهاد می‌دهد. اجرای تابع واقعی باید در Backend یا Script کنترل‌شده شما انجام شود.

چگونه زمان پاسخ را ببینیم؟

از -w استفاده کنید:

-w "%{time_total}\n"

چگونه Timeout تعیین کنیم؟

--connect-timeout 5
--max-time 60

آیا cURL خودکار Retry می‌کند؟

می‌توانید با --retry Retry محدود تعریف کنید، اما برای همه خطاها و عملیات‌ها مناسب نیست. Retry می‌تواند هزینه اضافی یا اجرای تکراری ایجاد کند.

چرا خطای 401 دریافت می‌کنم؟

API Key، مقدار Environment، Authorization Header و تکرارنشدن کلمه Bearer را بررسی کنید.

چرا خطای 400 دریافت می‌کنم؟

معمولاً JSON نامعتبر، پارامتر ناسازگار، مدل اشتباه، Context بزرگ یا Schema نامعتبر علت آن است.

آیا قراردادن API Key در فرمان امن است؟

برای آزمایش کوتاه ممکن است کار کند، اما Secret می‌تواند در History یا Log باقی بماند. استفاده از متغیر محیطی، فایل امن یا Secret Manager مناسب‌تر است.

جمع‌بندی

cURL یکی از سریع‌ترین و قابل‌حمل‌ترین ابزارها برای آزمایش API درواره است. با استفاده از آن می‌توانید بدون نصب SDK یا ساخت اپلیکیشن:

فهرست مدل‌ها را دریافت کنید؛
Chat Completion بفرستید؛
System Prompt و تاریخچه مکالمه را آزمایش کنید؛
Streaming را در Terminal ببینید؛
تصویر را با URL یا Base64 ارسال کنید؛
JSON Mode و Structured Outputs را تست کنید؛
Tool Calling را بررسی کنید؛
پاسخ را با jq پردازش کنید؛
Status، Header و زمان پاسخ را ببینید؛
Timeout و Retry محدود تعریف کنید؛
و درخواست‌های خود را وارد Postman یا کد برنامه کنید.

مهم‌ترین اصل این است که API Key را از فرمان‌ها، History، Git و Logهای قابل‌اشتراک دور نگه دارید. پس از تأیید درخواست با cURL، همان ساختار را می‌توانید با SDKهای Python، JavaScript یا زبان موردنظر خود وارد اپلیکیشن واقعی کنید.

شروع کار با API درواره

درواره زیرساخت دسترسی به مدل‌های مختلف هوش مصنوعی را از طریق یک API سازگار با OpenAI فراهم می‌کند.

Base URL:

https://api.darvareh.ir/v1

اولین آزمایش:

curl https://api.darvareh.ir/v1/models \
  -H "Authorization: Bearer $DARVAREH_API_KEY"

پس از دریافت فهرست مدل‌ها، شناسه مدل مناسب را انتخاب و درخواست Chat، Vision یا قابلیت موردنیاز را با توجه به پشتیبانی همان مدل اجرا کنید.

مقدمه

فهرست مطالب

cURL چیست؟

چرا از cURL برای API هوش مصنوعی استفاده کنیم؟

تقریباً همه‌جا در دسترس است

به رابط گرافیکی نیاز ندارد

برای Debug مناسب است

قابل انتقال است

برای آزمایش سریع مناسب است

برای اتوماسیون مناسب است

cURL چه جایگاهی در پروژه Production دارد؟

ساختار یک فرمان cURL

URL

Method

Header

Body

ادامه فرمان در خط بعد

بررسی نصب cURL

نصب cURL در Linux

Ubuntu و Debian

Fedora

CentOS و RHEL

Arch Linux

نصب cURL در macOS

استفاده از cURL در Windows

تفاوت curl و curl.exe در PowerShell

نصب jq

Ubuntu و Debian

Fedora

macOS

Windows با Winget

بررسی نصب

پیش‌نیازهای اتصال به API درواره

روش احراز هویت

استفاده مستقیم از API Key

تنظیم API Key در Linux و macOS

تنظیم API Key در PowerShell

تنظیم API Key در Command Prompt

نکته امنیتی درباره فایل‌های Shell

دریافت فهرست مدل‌ها

Linux و macOS

PowerShell

بدون متغیر

پاسخ احتمالی

نمایش خوانای فهرست مدل‌ها با jq

فقط شناسه مدل‌ها

مرتب‌سازی شناسه‌ها

جست‌وجو در مدل‌ها

ذخیره فهرست مدل‌ها در فایل

ارسال اولین Chat Completion

Linux و macOS

PowerShell

Command Prompt

پاسخ Chat Completions

نمایش فقط متن پاسخ

نمایش Usage

فقط مجموع Tokenها

مدل واقعی پاسخ

دلیل توقف

ساخت فایل JSON درخواست

چرا --data-binary؟

مزایای Body در فایل

نکته امنیتی

بررسی معتبر‌بودن JSON با jq

استفاده از System Prompt

ارسال تاریخچه مکالمه

ساخت JSON پویا با jq

ذخیره پاسخ در فایل

مشاهده Response Headers

فقط Headerها

ذخیره Headerها در فایل

نمایش HTTP Status Code

نمایش Status و زمان

اندازه‌گیری زمان‌های مختلف

تفسیر

حالت Verbose

هشدار امنیتی

تست Streaming

ساختار Streaming

Streaming در PowerShell

تفاوت `curl` و `curl.exe` در PowerShell

چرا `--data-binary`؟

استفاده از `.netrc`

استفاده از `.env`