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

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

در این راهنمای عملی، اتصال API درواره به Postman را از صفر می‌آموزید؛ از تنظیم API Key و دریافت مدل‌ها تا تست Chat، Vision، Structured Outputs، Streaming و مدیریت خطا، بدون نیاز به نوشتن یک اپلیکیشن کامل.

Darvareh API - Postman

مقدمه

برای استفاده از API مدل‌های هوش مصنوعی معمولاً نمونه‌کدهایی با Python، JavaScript یا زبان‌های دیگر ارائه می‌شود. اما همیشه لازم نیست برای آزمایش یک Endpoint، برنامه کاملی بنویسیم.

گاهی فقط می‌خواهیم:

اعتبار API Key را بررسی کنیم؛
فهرست مدل‌ها را دریافت کنیم؛
یک Prompt را با چند مدل آزمایش کنیم؛
بدنه JSON درخواست را تغییر دهیم؛
Response کامل و Headerها را ببینیم؛
خطاهای API را بررسی کنیم؛
Streaming را آزمایش کنیم؛
یک مدل Vision را با تصویر تست کنیم؛
Structured Outputs یا Tool Calling را بررسی کنیم؛
درخواست آماده را با اعضای تیم به اشتراک بگذاریم.

Postman برای این سناریوها ابزار بسیار مناسبی است. با Postman می‌توانید بدون ساخت رابط کاربری یا Backend، مستقیماً درخواست HTTP بسازید، Header و Body را تنظیم کنید، پاسخ را ببینید و برای آن تست خودکار بنویسید.

در این مقاله اتصال Postman به API سازگار با OpenAI درواره را از صفر و به‌صورت مرحله‌به‌مرحله انجام می‌دهیم.

فهرست مطالب

Postman چیست؟
چرا از Postman برای تست API هوش مصنوعی استفاده کنیم؟
پیش‌نیازهای اتصال به درواره
ساخت Workspace و Collection
تعریف Environment
نگهداری امن API Key
تنظیم Authorization در سطح Collection
دریافت فهرست مدل‌ها
ارسال اولین Chat Completion
ساخت System Prompt
ارسال تاریخچه مکالمه
تغییر پارامترهای مدل
فعال‌کردن Streaming
تست مدل‌های Vision با URL
ارسال تصویر Base64
تست JSON Mode
تست Structured Outputs
تست Tool Calling
ادامه مکالمه پس از Tool Call
تست تولید تصویر
نوشتن Test Script
ذخیره Usage و Request ID
استفاده از Pre-request Script
اجرای Collection Runner
واردکردن درخواست cURL
مدیریت خطاهای API
اشتراک‌گذاری امن Collection
ساختار پیشنهادی Collection
نکات امنیتی
چک‌لیست تست
پرسش‌های متداول
جمع‌بندی

Postman چیست؟

Postman یک پلتفرم برای طراحی، ارسال، تست، مستندسازی و همکاری روی APIهاست.

در ساده‌ترین حالت، Postman یک API Client گرافیکی است که به شما اجازه می‌دهد موارد زیر را مشخص کنید:

روش درخواست مانند GET یا POST
URL
Query Parameters
Headerها
Authorization
Body
فایل‌های ورودی
Scriptهای قبل و بعد از درخواست

پس از ارسال درخواست نیز می‌توانید این اطلاعات را مشاهده کنید:

HTTP Status
Response Headers
Response Body
زمان پاسخ
حجم پاسخ
Cookieها
نتایج Testها

Postman علاوه بر HTTP از پروتکل‌های دیگری مانند WebSocket و gRPC نیز پشتیبانی می‌کند، اما در این آموزش از درخواست‌های HTTP استفاده می‌کنیم. راهنمای ارسال درخواست در Postman

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

آزمایش بدون ساخت برنامه

پیش از نوشتن Backend یا Frontend، می‌توانید مطمئن شوید API Key، مدل و فرمت درخواست درست هستند.

مشاهده دقیق Request و Response

Postman امکان بررسی Headerها، Status و بدنه خام پاسخ را فراهم می‌کند.

تغییر سریع Prompt

بدون ویرایش و اجرای دوباره کد، می‌توانید Prompt یا پارامترها را تغییر دهید.

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

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

تست خودکار

می‌توانید بررسی کنید:

Status برابر 200 است؛
پاسخ دارای choices است؛
مدل محتوا برگردانده است؛
Usage وجود دارد؛
خروجی JSON معتبر است؛
زمان پاسخ از سقف مشخصی بیشتر نیست.

همکاری تیمی

Collectionها را می‌توان سازمان‌دهی و با تیم به اشتراک گذاشت، بدون اینکه لازم باشد کلید شخصی API داخل Collection قرار بگیرد.

API درواره

درواره یک API سازگار با OpenAI ارائه می‌دهد. آدرس پایه API:

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

برای درخواست‌های JSON نیز Header زیر لازم است:

Content-Type: application/json

پیش‌نیازهای آموزش

برای ادامه به موارد زیر نیاز دارید:

حساب کاربری درواره
API Key معتبر درواره
موجودی یا اعتبار کافی برای اجرای مدل
Postman Desktop یا نسخه Web با Desktop Agent
شناسه یک مدل فعال از فهرست مدل‌های درواره

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

MODEL_ID

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

قابلیت‌هایی مانند Vision، Tool Calling، Structured Outputs و Streaming به مدل انتخابی وابسته‌اند. همه مدل‌ها الزاماً از همه این قابلیت‌ها پشتیبانی نمی‌کنند.

ساخت Workspace در Postman

Workspace محیطی برای نگهداری Collectionها، Environmentها و درخواست‌های مرتبط است.

برای ساخت Workspace:

Postman را باز کنید.
از بخش Workspaces وارد صفحه Workspaceها شوید.
گزینه ساخت Workspace جدید را انتخاب کنید.
نام آن را وارد کنید:

Darvareh API

نوع دسترسی را مشخص کنید.
Workspace را ایجاد کنید.

اگر فقط خودتان از آن استفاده می‌کنید، Workspace شخصی یا خصوصی مناسب است. برای تیم، دسترسی‌ها را براساس نیاز تنظیم کنید.

ساخت Collection

Collection مجموعه‌ای از درخواست‌های مرتبط است.

برای ساخت Collection:

در Sidebar روی Collections بروید.
گزینه ساخت Collection جدید را انتخاب کنید.
نام Collection را وارد کنید:

Darvareh AI API

در صورت تمایل توضیح زیر را اضافه کنید:

Requests for testing the Darvareh OpenAI-compatible API.

ساختار پیشنهادی Collection:

Darvareh AI API
  ├── Models
  │   └── List Models
  ├── Chat
  │   ├── Basic Chat Completion
  │   ├── System Prompt
  │   ├── Conversation History
  │   └── Streaming Chat
  ├── Vision
  │   ├── Image URL
  │   └── Base64 Image
  ├── Structured Outputs
  │   ├── JSON Mode
  │   └── JSON Schema
  ├── Tools
  │   └── Tool Calling
  ├── Images
  │   └── Generate Image
  └── Errors
      ├── Invalid API Key
      ├── Invalid Model
      └── Rate Limit Test

تعریف Environment

Environment مجموعه‌ای از Variableهاست که می‌توانید در درخواست‌ها استفاده کنید.

برای ایجاد Environment:

در Sidebar وارد بخش Environments شوید.
یک Environment جدید بسازید.
نام آن را قرار دهید:

Darvareh Development

Variableهای زیر را اضافه کنید:

Variable	مقدار
`base_url`	`https://api.darvareh.ir/v1`
`api_key`	کلید API درواره
`model_id`	شناسه مدل منتخب
`last_request_id`	خالی
`last_prompt_tokens`	خالی
`last_completion_tokens`	خالی

پس از ذخیره Environment، آن را از منوی بالای Postman فعال کنید.

Postman امکان گروه‌بندی و استفاده مجدد از Variableها در Environmentهای مختلف را فراهم می‌کند. مستندات Environment در Postman

استفاده از Variable در Postman

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

{{base_url}}

برای مثال:

{{base_url}}/models

هنگام ارسال درخواست، Postman مقدار base_url را جایگزین می‌کند.

برای شناسه مدل:

{
  "model": "{{model_id}}"
}

و برای API Key:

{{api_key}}

Scope متغیرها در Postman

Variableها می‌توانند Scopeهای مختلفی داشته باشند:

Global
Collection
Environment
Data
Local
Vault

برای پروژه درواره پیشنهاد می‌شود:

base_url در Collection یا Environment ذخیره شود.
model_id در Environment یا Collection ذخیره شود.
api_key در Postman Vault یا Variable امن قرار گیرد.
داده‌های موقت مانند Request ID در Environment ذخیره شوند.

نگهداری امن API Key

API Key یک Secret است. آن را داخل Body، نام درخواست، توضیحات Collection یا متغیر عمومی اشتراکی قرار ندهید.

بهترین گزینه استفاده از Postman Vault است. Postman Vault برای نگهداری Secretهایی مانند API Key و Token طراحی شده و Local Vault مقادیر را روی دستگاه نگه می‌دارد و با Cloud همگام نمی‌کند. مستندات Postman Vault

ساخت Secret در Vault

Postman Vault را باز کنید.
یک Secret جدید بسازید.
نام Secret را قرار دهید:

darvareh-api-key

مقدار API Key را وارد کنید.
Secret را ذخیره کنید.

استفاده مستقیم از Vault

در فیلد Token می‌توانید از این مقدار استفاده کنید:

{{vault:darvareh-api-key}}

Postman از ساختار {{vault:secret-name}} برای ارجاع مستقیم به Secretهای Local Vault پشتیبانی می‌کند. استفاده از Secretهای Vault

اگر Vault در نسخه یا تنظیمات شما در دسترس نیست، api_key را به‌عنوان Variable امن و غیرقابل‌اشتراک نگهداری کنید.

تنظیم Authorization در سطح Collection

به‌جای افزودن Authorization به تک‌تک درخواست‌ها، آن را در سطح Collection تعریف کنید.

Collection را باز کنید.
وارد تب Authorization شوید.
Auth Type را روی Bearer Token قرار دهید.
در بخش Token بنویسید:

{{api_key}}

یا اگر از Vault استفاده می‌کنید:

{{vault:darvareh-api-key}}

تغییرات را ذخیره کنید.

Postman به‌صورت خودکار Header زیر را می‌سازد:

Authorization: Bearer YOUR_API_KEY

Postman برای Bearer Token، مقدار واردشده را با Prefix مربوط به Bearer در Header درخواست قرار می‌دهد. انواع Authorization در Postman

ارث‌بری Authorization

در هر درخواست، Authorization را روی گزینه زیر قرار دهید:

Inherit auth from parent

در این حالت درخواست از تنظیمات Collection استفاده می‌کند.

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

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

ساخت Request

در پوشه Models یک Request جدید بسازید.
نام آن را قرار دهید:

List Models

Method را روی GET قرار دهید.
URL را وارد کنید:

{{base_url}}/models

Authorization را روی Inherit auth from parent قرار دهید.
روی Send کلیک کنید.

نمونه Request

GET https://api.darvareh.ir/v1/models
Authorization: Bearer YOUR_DARVAREH_API_KEY

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

پاسخ رابط‌های سازگار با OpenAI معمولاً ساختاری شبیه این دارد:

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

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

انتخاب شناسه مدل

مقدار id مدلی را که می‌خواهید آزمایش کنید کپی و در Environment ذخیره کنید:

model_id = MODEL_ID

تست پاسخ فهرست مدل‌ها

وارد بخش Scripts و سپس Post-response شوید و این کد را اضافه کنید:

pm.test("Status code is 200", function () {
  pm.response.to.have.status(200);
});

pm.test("Response contains model data", function () {
  const json = pm.response.json();

  pm.expect(json).to.have.property("data");
  pm.expect(json.data).to.be.an("array");
});

Postman اجازه می‌دهد در تب Post-response با JavaScript پاسخ را بررسی و Test تعریف کنید. نوشتن Test در Postman

ذخیره خودکار اولین مدل

اگر فقط برای آزمایش می‌خواهید شناسه اولین مدل را ذخیره کنید:

const json = pm.response.json();

if (Array.isArray(json.data) && json.data.length > 0) {
  pm.environment.set("model_id", json.data[0].id);
}

این روش در آموزش مفید است، اما برای Production Test بهتر است مدل مشخصی را صریحاً انتخاب کنید؛ زیرا ترتیب فهرست مدل‌ها ممکن است تغییر کند.

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

در پوشه Chat یک Request جدید بسازید.

تنظیمات Request

نام:

Basic Chat Completion

Method:

POST

URL:

{{base_url}}/chat/completions

Authorization:

Inherit auth from parent

در تب Headers بررسی کنید Header زیر وجود داشته باشد:

Content-Type: application/json

اگر وجود ندارد، آن را اضافه کنید.

Body

به تب Body بروید و گزینه‌های زیر را انتخاب کنید:

raw
JSON

سپس Body را وارد کنید:

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

روی Send کلیک کنید.

پاسخ احتمالی

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

همه مدل‌ها یا Providerها الزاماً تمام فیلدها را با ساختار کاملاً یکسان برنمی‌گردانند. کد و Testهای شما باید نبود فیلدهای اختیاری را مدیریت کنند.

نقش‌های پیام

در Chat Completions، پیام‌ها معمولاً شامل role و content هستند.

System

رفتار کلی مدل را مشخص می‌کند:

{
  "role": "system",
  "content": "شما یک مدرس برنامه‌نویسی هستید."
}

User

درخواست کاربر:

{
  "role": "user",
  "content": "API چیست؟"
}

Assistant

پاسخ قبلی مدل یا بخشی از تاریخچه:

{
  "role": "assistant",
  "content": "API رابطی برای ارتباط میان نرم‌افزارهاست."
}

Tool

نتیجه اجرای یک ابزار در Workflowهای Tool Calling.

پشتیبانی دقیق نقش‌ها و شکل Content به مدل و رابط استفاده‌شده وابسته است.

استفاده از System Prompt

Body را به شکل زیر تغییر دهید:

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

از System Prompt برای تعیین موارد زیر استفاده کنید:

نقش
زبان
سبک پاسخ
قواعد
محدودیت‌ها
نحوه استفاده از Context
قالب خروجی

اطلاعات محرمانه یا Secret را در System Prompt قرار ندهید.

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

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

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

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

پارامترهای رایج درخواست

`model`

شناسه مدل:

{
  "model": "{{model_id}}"
}

`temperature`

میزان تنوع پاسخ را کنترل می‌کند:

{
  "temperature": 0.2
}

مقادیر پایین‌تر برای استخراج داده، دسته‌بندی و پاسخ‌های دقیق مناسب‌ترند. محدوده مجاز و اثر دقیق پارامتر به مدل بستگی دارد.

`max_tokens`

حداکثر Token خروجی را محدود می‌کند:

{
  "max_tokens": 500
}

برخی APIها یا مدل‌های جدید ممکن است از نام پارامتر دیگری مانند max_completion_tokens استفاده کنند. قابلیت و پارامترهای مدل انتخابی را بررسی کنید.

`top_p`

روش دیگری برای کنترل تنوع:

{
  "top_p": 0.9
}

معمولاً بهتر است temperature و top_p را هم‌زمان بدون دلیل تغییر ندهید.

`stream`

Streaming را فعال می‌کند:

{
  "stream": true
}

Body کامل

{
  "model": "{{model_id}}",
  "messages": [
    {
      "role": "system",
      "content": "پاسخ را دقیق و فارسی بنویس."
    },
    {
      "role": "user",
      "content": "سه کاربرد API هوش مصنوعی در فروشگاه اینترنتی را توضیح بده."
    }
  ],
  "temperature": 0.2,
  "max_tokens": 700,
  "stream": false
}

پارامترهای پشتیبانی‌شده میان مدل‌ها متفاوت‌اند. ارسال پارامتر ناسازگار می‌تواند خطای 400 ایجاد کند یا در بعضی مسیرها نادیده گرفته شود.

مشاهده زمان پاسخ

پس از Send، Postman زمان پاسخ را نمایش می‌دهد. این عدد معمولاً زمان کامل درخواست از دید Postman است.

برای ارزیابی دقیق‌تر AI به معیارهای زیر نیز نیاز داریم:

Time to First Token
Provider Latency
Total Generation Time
Tokens per Second

Postman برای بررسی دستی زمان کل مناسب است، اما برای Monitoring مستمر بهتر است این Metrics در Backend ثبت شوند.

فعال‌کردن Streaming

در Request جدید Body زیر را وارد کنید:

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

Postman می‌تواند Server-Sent Events یا SSE را دریافت و رویدادها را هنگام رسیدن نمایش دهد. نمایش SSE در Postman

در رابط‌های OpenAI-compatible، Chunkها ممکن است به این شکل باشند:

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

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

data: [DONE]

نکات Streaming

Response یک JSON واحد نیست.
هر Chunk بخشی از پاسخ است.
ممکن است آخرین Chunk شامل Usage باشد.
قطع اتصال می‌تواند پاسخ را ناقص کند.
Test Scriptهای معمول JSON برای Stream مناسب نیستند.
مدل انتخابی باید Streaming را پشتیبانی کند.

دریافت Usage در Streaming

در بعضی مدل‌ها و مسیرهای سازگار می‌توانید این گزینه را اضافه کنید:

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

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

تست مدل Vision با URL تصویر

مدل انتخابی باید ورودی تصویر را پشتیبانی کند.

یک Request جدید با URL زیر بسازید:

{{base_url}}/chat/completions

Body:

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

شرایط URL تصویر

URL باید از سمت Provider قابل‌دسترسی باشد.
بهتر است HTTPS باشد.
URL خصوصی یا Localhost از اینترنت در دسترس نیست.
لینک موقت نباید قبل از پردازش منقضی شود.
فرمت و حجم تصویر باید با محدودیت مدل سازگار باشد.

ترتیب Text و Image

برای وضوح بیشتر ابتدا دستور متنی و سپس تصویر را قرار دهید:

[
  {
    "type": "text",
    "text": "متن داخل تصویر را استخراج کن."
  },
  {
    "type": "image_url",
    "image_url": {
      "url": "https://example.com/invoice.jpg"
    }
  }
]

ارسال تصویر Base64

برای فایل Local یا خصوصی می‌توانید در مدل‌های پشتیبانی‌شده از Data URL استفاده کنید:

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,BASE64_DATA"
  }
}

Body کامل:

{
  "model": "{{model_id}}",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "اطلاعات این فاکتور را استخراج کن."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,{{image_base64}}"
          }
        }
      ]
    }
  ]
}

ساخت Base64 خارج از Postman

در Linux یا macOS:

base64 -i invoice.jpg

در برخی سیستم‌های Linux:

base64 invoice.jpg

در PowerShell:

[Convert]::ToBase64String(
  [IO.File]::ReadAllBytes("invoice.jpg")
)

مقدار را در Variable محلی image_base64 قرار دهید.

نکات Base64

Base64 اندازه داده را افزایش می‌دهد.
Environment اشتراکی محل مناسبی برای تصویر بزرگ نیست.
Postman و Provider ممکن است محدودیت Body داشته باشند.
برای تصویر عمومی، URL معمولاً ساده‌تر و کارآمدتر است.
داده حساس را در Variable ابری ذخیره نکنید.

تست JSON Mode

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

Body:

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

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

{
  "name": "هدفون بی‌سیم مدل X",
  "color": "مشکی",
  "price_toman": 4500000
}

مدل انتخابی و Provider باید response_format و json_object را پشتیبانی کنند.

تست Structured Outputs

Structured Outputs علاوه بر JSON معتبر، ساختار خروجی را با JSON Schema مشخص می‌کند.

{
  "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
}

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

{
  "name": "هدفون بی‌سیم مدل X",
  "color": "مشکی",
  "price_toman": 4500000,
  "features": [
    "حذف نویز فعال"
  ]
}

نکته مهم

همه مدل‌ها از json_schema یا strict پشتیبانی نمی‌کنند. اگر خطای پارامتر دریافت کردید:

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

Test Script برای Structured Outputs

در تب Post-response:

pm.test("Status code is 200", function () {
  pm.response.to.have.status(200);
});

pm.test("Model returned content", function () {
  const response = pm.response.json();
  const content = response.choices?.[0]?.message?.content;

  pm.expect(content).to.be.a("string");
  pm.expect(content.length).to.be.greaterThan(0);
});

pm.test("Content is valid JSON", function () {
  const response = pm.response.json();
  const content = response.choices[0].message.content;

  const data = JSON.parse(content);

  pm.expect(data).to.have.property("name");
  pm.expect(data).to.have.property("color");
  pm.expect(data).to.have.property("price_toman");
  pm.expect(data.features).to.be.an("array");
});

توجه کنید که JSON ساختاریافته معمولاً داخل message.content به‌شکل String قرار دارد و باید یک بار دیگر با JSON.parse تبدیل شود.

تست Tool Calling

Tool Calling به مدل اجازه می‌دهد تشخیص دهد برای پاسخ به درخواست کاربر، یک تابع یا ابزار فراخوانی شود.

فرض کنید تابع زیر در Backend شما وجود دارد:

get_order_status(order_id)

در Postman می‌توانیم ببینیم مدل چه Tool Callی پیشنهاد می‌دهد.

{
  "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"
}

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

{
  "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 را بررسی کند.
آرگومان‌ها را Parse و Validate کند.
مجوز کاربر را بررسی کند.
تابع واقعی را اجرا کند.
نتیجه را به مدل برگرداند.
پاسخ نهایی را دریافت کند.

بررسی Tool Call در Test Script

pm.test("Tool call exists", function () {
  const response = pm.response.json();
  const toolCalls =
    response.choices?.[0]?.message?.tool_calls;

  pm.expect(toolCalls).to.be.an("array");
  pm.expect(toolCalls.length).to.be.greaterThan(0);
});

pm.test("Correct tool selected", function () {
  const response = pm.response.json();
  const toolCall =
    response.choices[0].message.tool_calls[0];

  pm.expect(toolCall.function.name)
    .to.eql("get_order_status");

  const args = JSON.parse(
    toolCall.function.arguments
  );

  pm.expect(args.order_id).to.eql("ORD-2048");
});

ادامه مکالمه پس از Tool Call

فرض کنید Backend وضعیت سفارش را چنین برگردانده است:

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

در درخواست بعدی باید پیام Assistant دارای Tool Call و سپس نتیجه Tool ارسال شود.

ساختار رایج:

{
  "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
        }
      }
    }
  ]
}

مدل می‌تواند پاسخ نهایی طبیعی تولید کند:

سفارش ORD-2048 ارسال شده است و کد رهگیری آن TR-5521 است.

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

تست تولید تصویر

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

{{base_url}}/images/generations

Body نمونه:

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

نکته مهم

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

size
width
height
aspect_ratio
quality
output_format
n
response_format

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

تست Response اصلی Chat

برای درخواست Basic Chat در Post-response:

pm.test("Status is successful", function () {
  pm.response.to.have.status(200);
});

pm.test("Response is JSON", function () {
  pm.response.to.be.json;
});

pm.test("Choices array exists", function () {
  const json = pm.response.json();

  pm.expect(json.choices).to.be.an("array");
  pm.expect(json.choices.length).to.be.greaterThan(0);
});

pm.test("Assistant returned content", function () {
  const json = pm.response.json();
  const message = json.choices[0].message;

  pm.expect(message).to.have.property("role");
  pm.expect(message.role).to.eql("assistant");
  pm.expect(message.content).to.be.a("string");
});

pm.test("Response time is below 30 seconds", function () {
  pm.expect(pm.response.responseTime)
    .to.be.below(30000);
});

Testها پس از دریافت پاسخ اجرا می‌شوند و نتیجه آن‌ها در بخش Test Results قابل‌مشاهده است. نمونه‌های Test Script در Postman

ذخیره Usage در Environment

const json = pm.response.json();

if (json.usage) {
  if (json.usage.prompt_tokens !== undefined) {
    pm.environment.set(
      "last_prompt_tokens",
      String(json.usage.prompt_tokens)
    );
  }

  if (json.usage.completion_tokens !== undefined) {
    pm.environment.set(
      "last_completion_tokens",
      String(json.usage.completion_tokens)
    );
  }

  if (json.usage.total_tokens !== undefined) {
    pm.environment.set(
      "last_total_tokens",
      String(json.usage.total_tokens)
    );
  }
}

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

ذخیره Response ID

const json = pm.response.json();

if (json.id) {
  pm.environment.set(
    "last_response_id",
    json.id
  );
}

ذخیره Request ID از Header

نام Header بالادستی می‌تواند متفاوت باشد. Script انعطاف‌پذیر:

const candidateHeaders = [
  "x-request-id",
  "request-id",
  "openai-request-id"
];

let requestId = null;

for (const headerName of candidateHeaders) {
  const value = pm.response.headers.get(headerName);

  if (value) {
    requestId = value;
    break;
  }
}

if (requestId) {
  pm.environment.set(
    "last_request_id",
    requestId
  );
}

اگر Header موردنظر در پاسخ فعلی وجود ندارد، Variable تغییری نمی‌کند.

ثبت مدل واقعی پاسخ‌دهنده

const json = pm.response.json();

if (json.model) {
  pm.environment.set(
    "last_response_model",
    json.model
  );
}

این موضوع در معماری‌های Routing و Fallback مهم است، زیرا مدل واقعی پاسخ‌دهنده ممکن است با Alias یا مدل درخواستی تفاوت داشته باشد.

Pre-request Script

Pre-request Script پیش از ارسال درخواست اجرا می‌شود و برای ساخت مقادیر پویا مناسب است.

در تب Scripts و سپس Pre-request:

const requestId = `postman-${Date.now()}-${Math.random()
  .toString(36)
  .slice(2)}`;

pm.variables.set(
  "client_request_id",
  requestId
);

سپس می‌توانید Header زیر را اضافه کنید:

X-Client-Request-ID: {{client_request_id}}

این Header فقط در صورتی در سمت سرور کاربرد دارد که API آن را قبول، منتقل یا ثبت کند. در غیر این صورت صرفاً برای سازمان‌دهی تست‌های خودتان قابل‌استفاده است.

ساخت Prompt به‌صورت Variable

در Environment:

test_prompt

در Body:

{
  "model": "{{model_id}}",
  "messages": [
    {
      "role": "user",
      "content": "{{test_prompt}}"
    }
  ]
}

این روش امکان اجرای همان درخواست با Promptهای مختلف را فراهم می‌کند.

مراقب Escape در JSON باشید

اگر مقدار Variable شامل نقل‌قول، خط جدید یا JSON باشد، جایگزینی مستقیم ممکن است Body را نامعتبر کند.

برای داده پیچیده بهتر است Body را در Pre-request Script بسازید یا Variable را به‌شکل JSON-safe ذخیره کنید.

ساخت Body پویا با Pre-request Script

const prompt =
  pm.environment.get("test_prompt") ||
  "یک توضیح کوتاه درباره API بنویس.";

const body = {
  model: pm.environment.get("model_id"),
  messages: [
    {
      role: "user",
      content: prompt,
    },
  ],
  temperature: 0.2,
  max_tokens: 500,
};

pm.variables.set(
  "dynamic_request_body",
  JSON.stringify(body)
);

در Body فقط بنویسید:

{{dynamic_request_body}}

و نوع Body را raw و JSON قرار دهید.

Collection Runner چیست؟

Collection Runner امکان اجرای چند Request به‌ترتیب و چند بار را فراهم می‌کند.

کاربردها:

Smoke Test
Regression Test
تست چند مدل
تست چند Prompt
بررسی خطاها
اجرای Workflow ساده
مشاهده Test Resultها

اجرای Collection

Collection را باز کنید.
گزینه Run را انتخاب کنید.
Environment درواره را انتخاب کنید.
Requestهای موردنظر را انتخاب کنید.
تعداد Iteration را تعیین کنید.
Runner را اجرا کنید.
نتیجه Testها را بررسی کنید.

Data-driven Testing

می‌توانید داده‌های مختلف را از CSV یا JSON به Runner بدهید.

نمونه CSV:

model_id,test_prompt,expected_language
MODEL_A,"API چیست؟",fa
MODEL_B,"Explain RAG briefly.",en

در Request:

{
  "model": "{{model_id}}",
  "messages": [
    {
      "role": "user",
      "content": "{{test_prompt}}"
    }
  ]
}

Variableهای Data در اجرای Runner برای هر ردیف جایگزین می‌شوند.

نکته هزینه

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

تعداد ردیف‌ها را بررسی کنید.
مدل و قیمت را بررسی کنید.
max_tokens را محدود کنید.
ابتدا با چند نمونه اجرا کنید.
موجودی حساب را در نظر بگیرید.

مقایسه مدل‌ها در Collection Runner

یک Dataset بسازید:

[
  {
    "model_id": "MODEL_A",
    "test_prompt": "یک ایمیل رسمی کوتاه بنویس."
  },
  {
    "model_id": "MODEL_B",
    "test_prompt": "یک ایمیل رسمی کوتاه بنویس."
  }
]

سپس این Metricها را ثبت کنید:

Response Time
Input Tokens
Output Tokens
Response Model
Finish Reason
Valid JSON
Test Success

Postman برای مقایسه دستی و تست عملکرد API مناسب است، اما ارزیابی دقیق کیفیت مدل به Dataset، Rubric و ابزار Evaluation جداگانه نیاز دارد.

واردکردن cURL به Postman

اگر نمونه cURL در اختیار دارید، لازم نیست Request را دستی بسازید.

نمونه:

curl https://api.darvareh.ir/v1/chat/completions \
  -H "Authorization: Bearer YOUR_DARVAREH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "سلام"
      }
    ]
  }'

برای Import:

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

Postman امکان واردکردن cURL به‌عنوان Request جدید یا ذخیره مستقیم آن در Collection را دارد. راهنمای Import cURL در Postman

تولید cURL از Postman

پس از ساخت Request می‌توانید از گزینه Code Snippet، نمونه کد یا cURL آن را دریافت کنید.

قبل از اشتراک‌گذاری:

API Key را حذف کنید.
Secretها را با Placeholder جایگزین کنید.
URLهای خصوصی را بررسی کنید.
داده‌های حساس Body را حذف کنید.

مدیریت خطای 400

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

دلایل رایج:

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

بررسی JSON

مطمئن شوید Body روی raw و JSON قرار دارد:

{
  "model": "{{model_id}}",
  "messages": [
    {
      "role": "user",
      "content": "سلام"
    }
  ]
}

نمونه اشتباه:

{
  "model": "{{model_id}}",
  "messages": [
    {
      "role": "user",
      "content": "سلام",
    }
  ]
}

JSON استاندارد ویرگول انتهایی را نمی‌پذیرد.

مدیریت خطای 401

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

بررسی کنید:

کلید کامل کپی شده است.
کلید منقضی یا Revoke نشده است.
Environment درست فعال است.
Variable مقدار دارد.
Authorization روی Bearer Token است.
کلمه Bearer را داخل Variable قرار نداده‌اید.

اگر Postman خودش Bearer را اضافه می‌کند، مقدار Token باید فقط خود کلید باشد:

{{api_key}}

نه:

Bearer {{api_key}}

در غیر این صورت Header ممکن است به‌شکل اشتباه ساخته شود:

Authorization: Bearer Bearer ...

مدیریت خطای 403

403 Forbidden یعنی هویت ممکن است شناخته شده باشد، اما دسترسی مجاز نیست.

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

عدم دسترسی به مدل
وضعیت حساب
محدودیت سازمان
سیاست امنیتی
Endpoint غیرمجاز

متن Error Response و Request ID را برای پشتیبانی نگه دارید، اما API Key را ارسال نکنید.

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

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

اقدامات:

موجودی کیف پول را بررسی کنید.
قیمت مدل و سقف خروجی را در نظر بگیرید.
درخواست غیرضروری را تکرار نکنید.
Request ID و زمان خطا را ثبت کنید.
پس از افزایش اعتبار دوباره آزمایش کنید.

کد HTTP ممکن است بسته به قرارداد نسخه فعلی API متفاوت باشد؛ بنابراین Client را براساس error.code و Status واقعی مستندشده پیاده‌سازی کنید، نه یک حدس ثابت.

مدیریت خطای 404

دلایل رایج:

اشتباه‌بودن URL
Endpoint ناموجود
شناسه مدل نامعتبر
حذف /v1
استفاده از Method اشتباه

آدرس درست Base URL:

https://api.darvareh.ir/v1

اشتباه:

https://api.darvareh.ir

اگر Request انتظار Endpoint نسخه اول را دارد، حذف /v1 می‌تواند Route متفاوت یا خطای 404 ایجاد کند.

مدیریت خطای 429

429 Too Many Requests معمولاً به محدودیت مصرف مربوط است:

RPM
TPM
Concurrency
Quota
درخواست‌های سریع و متوالی

راهکارها:

درخواست‌ها را با فاصله ارسال کنید.
max_tokens را کاهش دهید.
درخواست‌های تکراری را حذف کنید.
Concurrency را کم کنید.
Headerهایی مانند Retry-After را بررسی کنید.
از Retry فوری و نامحدود خودداری کنید.

Collection Runner می‌تواند در زمان کوتاه درخواست‌های زیادی ارسال کند. برای تست‌های بزرگ محدودیت API را در نظر بگیرید.

مدیریت خطاهای 500، 502، 503 و 504

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

اقدامات پیشنهادی:

Request ID را ذخیره کنید.
چند ثانیه صبر کنید.
درخواست را فقط به‌صورت محدود Retry کنید.
وضعیت مدل را بررسی کنید.
مدل جایگزین سازگار را آزمایش کنید.
در صورت تکرار، جزئیات غیرحساس را برای پشتیبانی ارسال کنید.

تست قرارداد خطا

در پوشه Errors یک Request با API Key نامعتبر بسازید، اما هرگز Secret واقعی را داخل آن ذخیره نکنید.

Post-response:

pm.test("Unauthorized request is rejected", function () {
  pm.expect(pm.response.code).to.be.oneOf([
    401,
    403
  ]);
});

pm.test("Error response contains error object", function () {
  const json = pm.response.json();

  pm.expect(json).to.have.property("error");
});

برای Rate Limit یا موجودی، فقط در محیط کنترل‌شده تست کنید. ایجاد عمدی بار زیاد روی Production روش مناسبی برای آزمایش 429 نیست.

استفاده از Postman Console

Postman Console برای Debug درخواست مفید است.

از Console می‌توانید موارد زیر را ببینید:

URL نهایی
Headerهای Request
Body نهایی
Variableهای جایگزین‌شده
خطاهای Script
اطلاعات شبکه

هنگام اشتراک Screenshot یا Log Console، Authorization Header و داده‌های حساس را حذف کنید.

ذخیره Example

پس از دریافت یک پاسخ مناسب می‌توانید آن را به‌عنوان Example ذخیره کنید.

Example برای این موارد مفید است:

مستندسازی
نمایش پاسخ موفق
نمایش خطا
Mock Server
آموزش اعضای تیم

Postman اجازه می‌دهد Response واقعی یا نمونه سفارشی را به Request متصل کنید. راهنمای Example در Postman

قبل از ذخیره Example:

API Key را حذف کنید.
اطلاعات شخصی را Redact کنید.
Request ID واقعی را عمومی نکنید.
محتوای محرمانه Prompt را حذف کنید.
شناسه‌های حساب را با مقدار ساختگی جایگزین کنید.

اشتراک‌گذاری Collection با تیم

Postman امکان همکاری، Comment و اشتراک Collection را فراهم می‌کند. همکاری روی Collectionها

اما Collection را بدون بررسی Secretها به اشتراک نگذارید.

موارد قابل‌اشتراک

Base URL عمومی
Endpointها
Bodyهای نمونه
Placeholder مدل
Test Scriptها
توضیحات
Exampleهای پاک‌سازی‌شده

موارد غیرقابل‌اشتراک

API Key واقعی
Token
اطلاعات کاربر
URL خصوصی
فایل محرمانه
Prompt حاوی اطلاعات سازمانی
داده‌های مالی

الگوی امن Collection

در Collection بنویسید:

{{api_key}}

و از هر عضو تیم بخواهید مقدار شخصی خود را در Vault یا Environment محلی قرار دهد.

Postman نیز استفاده از Vault برای نگهداری API Key و جلوگیری از افشای ناخواسته Secret را توصیه می‌کند. امنیت توسعه‌دهندگان در Postman

Environmentهای جداگانه

اگر چند محیط دارید، Environmentهای جدا بسازید:

Darvareh Development
Darvareh Staging
Darvareh Production

هر Environment می‌تواند Base URL، Model و تنظیمات متفاوت داشته باشد.

API Keyهای محیط‌ها را با هم مخلوط نکنید.

برای Production:

دسترسی محدودتر
API Key جداگانه
بودجه محدود
درخواست‌های کنترل‌شده
عدم اجرای تست پرحجم
عدم استفاده از داده ساختگی خطرناک در Toolهای Write

تست چند مدل بدون ویرایش Body

فقط Variable زیر را تغییر دهید:

model_id

همان Request با مدل دیگری اجرا می‌شود.

برای مقایسه منصفانه:

Prompt یکسان باشد.
پارامترها یکسان و پشتیبانی‌شده باشند.
زمان اجرا نزدیک باشد.
تعداد نمونه کافی باشد.
هزینه و Token ثبت شوند.
کیفیت به‌صورت جداگانه ارزیابی شود.

یک پاسخ منفرد برای نتیجه‌گیری درباره کیفیت مدل کافی نیست.

اسکریپت مقایسه‌ای ساده

در Post-response:

const json = pm.response.json();

const result = {
  model: json.model || pm.environment.get("model_id"),
  responseTimeMs: pm.response.responseTime,
  promptTokens: json.usage?.prompt_tokens ?? null,
  completionTokens:
    json.usage?.completion_tokens ?? null,
  totalTokens: json.usage?.total_tokens ?? null,
  finishReason:
    json.choices?.[0]?.finish_reason ?? null,
};

console.log("MODEL TEST RESULT", result);

نتیجه را در Postman Console مشاهده کنید.

تست ایمنی API Key

پیش از اشتراک Collection این موارد را بررسی کنید:

در URL کلید وجود ندارد.
در Header مقدار ثابت ذخیره نشده است.
Collection Variable مشترک حاوی Secret نیست.
Exampleها کلید را ندارند.
Console Screenshot پاک‌سازی شده است.
فایل Exportشده را بررسی کرده‌اید.
کلید در Pre-request Script نوشته نشده است.
کلید در CSV یا JSON Runner وجود ندارد.

اگر API Key ناخواسته منتشر شد:

فوراً آن را Revoke کنید.
کلید جدید بسازید.
Usage و فعالیت‌های غیرعادی را بررسی کنید.
محل افشا را پاک‌سازی کنید.
فقط حذف‌کردن فایل کافی نیست؛ کلید باید باطل شود.

ساختار پیشنهادی Collection نهایی

Darvareh AI API
  ├── 01 Models
  │   └── List Models
  ├── 02 Chat
  │   ├── Basic Chat
  │   ├── System Prompt
  │   ├── Conversation
  │   └── Streaming
  ├── 03 Vision
  │   ├── Image URL
  │   └── Image Base64
  ├── 04 Structured Output
  │   ├── JSON Mode
  │   └── JSON Schema
  ├── 05 Tools
  │   ├── Request Tool Call
  │   └── Submit Tool Result
  ├── 06 Images
  │   └── Generate Image
  ├── 07 Automated Tests
  │   ├── Response Contract
  │   └── Model Comparison
  └── 08 Error Cases
      ├── Invalid Key
      ├── Invalid Model
      └── Invalid Body

شماره‌گذاری پوشه‌ها ترتیب آموزش و اجرای Requestها را واضح‌تر می‌کند.

چک‌لیست اتصال درواره به Postman

تنظیم اولیه

Postman نصب یا آماده استفاده است.
Workspace ساخته شده است.
Collection درواره ساخته شده است.
Environment فعال است.
base_url برابر آدرس صحیح است.
شناسه مدل معتبر ثبت شده است.
API Key در Vault یا Variable امن قرار دارد.

Authorization

Collection روی Bearer Token تنظیم شده است.
Requestها Authorization را از Parent به ارث می‌برند.
API Key شامل کلمه Bearer نیست.
Header Authorization دوبار اضافه نشده است.
Secret داخل Collection ذخیره نشده است.

Chat

Method برابر POST است.
URL به /chat/completions ختم می‌شود.
Content-Type برابر application/json است.
Body از نوع Raw JSON است.
model و messages وجود دارند.
roleها صحیح‌اند.
max_tokens منطقی است.

Vision

مدل از تصویر پشتیبانی می‌کند.
URL تصویر عمومی و HTTPS است.
فرمت تصویر مجاز است.
تصویر Base64 دارای Data URL صحیح است.
اندازه Body از محدودیت عبور نمی‌کند.
اطلاعات خصوصی در Environment اشتراکی ذخیره نشده است.

Structured Outputs

مدل از JSON Mode یا JSON Schema پشتیبانی می‌کند.
Schema معتبر است.
فیلدهای ضروری در required قرار دارند.
additionalProperties تنظیم شده است.
محتوای خروجی دوباره Parse و Validate می‌شود.

Tool Calling

مدل از Tools پشتیبانی می‌کند.
نام Tool واضح است.
Parameters دارای JSON Schema معتبرند.
آرگومان‌های مدل Validate می‌شوند.
اجرای Tool در Backend انجام می‌شود.
مجوز کاربر مستقل بررسی می‌شود.
عملیات حساس بدون تأیید اجرا نمی‌شوند.

Streaming

مدل Streaming را پشتیبانی می‌کند.
stream برابر true است.
پاسخ به‌شکل SSE بررسی می‌شود.
قطع Stream به‌عنوان پاسخ کامل ثبت نمی‌شود.
احتمال نرسیدن Usage نهایی در نظر گرفته شده است.

تست و امنیت

Status Code تست می‌شود.
ساختار Response بررسی می‌شود.
Response Time ثبت می‌شود.
Usage ذخیره می‌شود.
Request ID در صورت وجود ثبت می‌شود.
Collection Runner با تعداد محدود آزمایش شده است.
API Key در Export و Exampleها وجود ندارد.
داده حساس از Logها حذف شده است.

اشتباهات رایج

قرارندادن `/v1` در Base URL

صحیح:

https://api.darvareh.ir/v1

قراردادن Endpoint دوباره در Base URL

اگر base_url این باشد:

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

و Request نیز بنویسد:

{{base_url}}/chat/completions

URL اشتباه می‌شود:

.../chat/completions/chat/completions

base_url باید فقط تا /v1 باشد.

انتخاب نکردن Environment

اگر Environment فعال نباشد، Postman ممکن است {{base_url}} را جایگزین نکند.

API Key همراه با Bearer

در فیلد Bearer Token فقط کلید را قرار دهید.

انتخاب مدل ناسازگار

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

استفاده از JSON نامعتبر

Postman ممکن است Body را ارسال کند، اما Server آن را رد می‌کند. ویرگول و نقل‌قول‌ها را بررسی کنید.

ذخیره API Key در Collection

Collection ممکن است با تیم یا Cloud همگام شود. از Vault استفاده کنید.

اجرای Runner بزرگ

هر ردیف می‌تواند هزینه واقعی ایجاد کند و Rate Limit را پر کند.

فرض اینکه Postman برنامه Production است

Postman ابزار تست و توسعه است. منطق امنیت، Retry، Billing، Validation و Tool Execution باید در Backend واقعی پیاده‌سازی شود.

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

آیا برای استفاده از Postman به برنامه‌نویسی نیاز دارم؟

برای ارسال درخواست‌های ساده خیر. کافی است Method، URL، Header و Body را وارد کنید. برای Test Scriptهای پیشرفته، آشنایی مقدماتی با JavaScript مفید است.

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

https://api.darvareh.ir/v1

API Key را کجا وارد کنیم؟

در تب Authorization نوع Bearer Token را انتخاب و API Key را از طریق Postman Vault یا Variable امن وارد کنید.

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

درخواست زیر را ارسال کنید:

GET {{base_url}}/models

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

یک درخواست POST به آدرس زیر بسازید:

{{base_url}}/chat/completions

و model و messages را در Body قرار دهید.

آیا Postman از Streaming پشتیبانی می‌کند؟

بله، Postman می‌تواند Server-Sent Events را دریافت و رویدادها را هنگام رسیدن نمایش دهد. مدل و API نیز باید Streaming را پشتیبانی کنند.

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

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

آیا Postman خودش Tool را اجرا می‌کند؟

خیر. مدل فقط Tool Call پیشنهادی را برمی‌گرداند. اجرای تابع واقعی برعهده Backend شماست. در Postman می‌توانید نتیجه فرضی Tool را در درخواست بعدی به مدل برگردانید.

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

JSON Mode خروجی JSON معتبر می‌خواهد، اما Schema دقیق را تضمین نمی‌کند. Structured Outputs خروجی را به JSON Schema مشخص محدود می‌کند؛ البته مدل باید از آن پشتیبانی کند.

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

API Key، Environment فعال، Bearer Token و تکرارنشدن کلمه Bearer را بررسی کنید.

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

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

آیا می‌توان Collection را با تیم به اشتراک گذاشت؟

بله، اما API Key و داده‌های حساس را داخل Collection قرار ندهید. هر عضو تیم باید Secret خود را در Vault یا Environment محلی تنظیم کند.

آیا تست‌های Postman هزینه دارند؟

خود Postman ممکن است براساس پلن شرایط خود را داشته باشد، اما هر درخواست واقعی به مدل می‌تواند مصرف و هزینه API ایجاد کند. Collection Runner نیز ممکن است چندین درخواست واقعی ارسال کند.

جمع‌بندی

Postman یکی از سریع‌ترین راه‌ها برای آشنایی و آزمایش API درواره است. بدون ساخت یک اپلیکیشن کامل می‌توانید:

API Key را بررسی کنید؛
مدل‌ها را دریافت کنید؛
Chat Completion اجرا کنید؛
System Prompt و تاریخچه بسازید؛
Streaming را ببینید؛
تصویر را به مدل Vision ارسال کنید؛
JSON Mode و Structured Outputs را آزمایش کنید؛
Tool Calling را بررسی کنید؛
Test Script بنویسید؛
و درخواست‌ها را در یک Collection منظم نگه دارید.

بااین‌حال، Postman جای Backend Production را نمی‌گیرد. در محصول واقعی باید API Key را در سرور نگه دارید و Rate Limit، Timeout، Retry، Validation، Billing، Monitoring و امنیت Toolها را در معماری اپلیکیشن پیاده‌سازی کنید.

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

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

https://api.darvareh.ir/v1

پس از آزمایش موفق در Postman، می‌توانید همان Request را به cURL، Python، JavaScript یا زبان برنامه‌نویسی موردنظر خود تبدیل و در اپلیکیشن واقعی استفاده کنید.