RozhNet AI API Documentation

RozhNet AI API Documentation

مستندات کامل API پلاگین RozhNet AI برای اتصال به مدل‌های هوش مصنوعی

Base URL: https://rozhnet.ir/wp-json/v1/chat

Authentication: Bearer Token (API Key)

1. Authentication

تمام درخواست‌ها باید شامل هدر Authorization با کلید API شما باشند:

HTTP Header 
Authorization: Bearer RN-your-real-api-key
هشدار امنیتی: کلید API خود را هرگز در کدهای سمت کلاینت (JavaScript) یا مخازن عمومی قرار ندهید. این کلید باید فقط در سمت سرور استفاده شود.

2. Endpoint

POST https://rozhnet.ir/wp-json/v1/chat

3. Request Types

Simple Text Request (JSON)

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

cURL 
curl -X POST "https://rozhnet.ir/wp-json/v1/chat" \
  -H "Authorization: Bearer RN-RN-your-real-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4-flash",
    "messages": [
      {
        "role": "user",
        "content": "Write a Python function to calculate fibonacci numbers"
      }
    ],
    "stream": false
  }'

Response Example:

JSON 
{
  "id": "gen-abc123",
  "object": "chat.completion",
  "created": 1704067200,
  "model": "deepseek/deepseek-v4-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "def fibonacci(n):\n    if n <= 1:\n        return n\n    return fibonacci(n-1) + fibonacci(n-2)"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 45,
    "total_tokens": 60,
    "cost": 1250.50
  }
}

Text File Upload (Multipart)

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

cURL 
curl -X POST "https://rozhnet.ir/wp-json/v1/chat" \
  -H "Authorization: Bearer RN-your-real-api-key" \
  -F "model=deepseek/deepseek-v4-flash" \
  -F 'messages=[{"role": "user", "content": "Analyze this code and suggest improvements"}]' \
  -F "file_attachment=@code.py"

Supported Text File Types:

Extension MIME Type Description
.txttext/plainPlain text files
.jsonapplication/jsonJSON data files
.csvtext/csvCSV spreadsheet files
.mdtext/markdownMarkdown documentation
.pytext/x-pythonPython source code
.jstext/javascriptJavaScript source code
.phptext/x-phpPHP source code
.htmltext/htmlHTML documents
.csstext/cssCSS stylesheets
.sqlapplication/sqlSQL queries
نکته: حداکثر حجم فایل 5 مگابایت است. محتوای فایل به صورت خودکار به 20,000 کاراکتر محدود می‌شود.

Image Upload (Vision Models)

برای پردازش تصاویر، باید از مدل‌های Vision-Capable مانند Google Gemini استفاده کنید:

cURL 
curl -X POST "https://rozhnet.ir/wp-json/v1/chat" \
  -H "Authorization: Bearer RN-your-real-api-key" \
  -F "model=google/gemini-3.5-flash" \
  -F 'messages=[{"role": "user", "content": "Describe this image in detail, including any text visible"}]' \
  -F "file_attachment=@photo.jpg"

Supported Image Formats:

Extension MIME Type Notes
.jpg, .jpegimage/jpegMost common format
.pngimage/pngSupports transparency
.gifimage/gifAnimated GIFs supported
.webpimage/webpModern format, better compression
مهم: اگر تصویری را به مدل متنی (مانند DeepSeek) ارسال کنید، خطای 404 دریافت خواهید کرد: "No endpoints found that support image input"

Vision-Capable Models:

  • google/gemini-3.5-flash - Fast and accurate
  • google/gemini-pro - Higher quality, slower
  • openai/gpt-4o - Best vision capabilities
  • openai/gpt-4o-mini - Cost-effective option
  • anthropic/claude-3-sonnet - Excellent reasoning

Multiple Files Upload

می‌توانید چندین فایل (متنی و تصویری) را همزمان ارسال کنید:

cURL 
curl -X POST "https://rozhnet.ir/wp-json/v1/chat" \
  -H "Authorization: Bearer RN-your-real-api-key" \
  -F "model=google/gemini-3.5-flash" \
  -F 'messages=[{"role": "user", "content": "Compare these two images and describe the differences"}]' \
  -F "file_attachment_0=@image1.jpg" \
  -F "file_attachment_1=@image2.png" \
  -F "file_attachment_2=@document.txt"
نکته: نام فیلدها باید منحصربه‌فرد باشند (file_attachment_0, file_attachment_1, ...). پلاگین به صورت خودکار تمام فایل‌ها را پردازش می‌کند.

Streaming Request

برای دریافت پاسخ به صورت تدریجی (مناسب برای رابط‌های کاربری زنده):

cURL 
curl -X POST "https://rozhnet.ir/wp-json/v1/chat" \
  -H "Authorization: Bearer RN-your-real-api-key" \
  -F "model=deepseek/deepseek-v4-flash" \
  -F 'messages=[{"role": "user", "content": "Write a long story about AI"}]' \
  -F "stream=true"

Streaming Response Format (Server-Sent Events):

SSE 
data: {"id":"gen-abc123","object":"chat.completion.chunk","created":1704067200,"model":"deepseek/deepseek-v4-flash","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"gen-abc123","object":"chat.completion.chunk","created":1704067200,"model":"deepseek/deepseek-v4-flash","choices":[{"index":0,"delta":{"content":"Once"},"finish_reason":null}]}

data: {"id":"gen-abc123","object":"chat.completion.chunk","created":1704067200,"model":"deepseek/deepseek-v4-flash","choices":[{"index":0,"delta":{"content":" upon"},"finish_reason":null}]}

data: {"id":"gen-abc123","object":"chat.completion.chunk","created":1704067200,"model":"deepseek/deepseek-v4-flash","choices":[{"index":0,"delta":{"content":" a time"},"finish_reason":null}]}

data: [DONE]
نکته: در حالت streaming، توکن‌های مصرفی به صورت تقریبی محاسبه می‌شوند (هر 4 کاراکتر = 1 توکن).

Base64 Direct (No File Upload)

اگر نمی‌خواهید فایل را آپلود کنید، می‌توانید تصویر را مستقیماً به صورت Base64 در JSON payload ارسال کنید:

cURL (Linux/Mac) 
curl -X POST "https://rozhnet.ir/wp-json/v1/chat" \
  -H "Authorization: Bearer RN-your-real-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What is in this image?"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/jpeg;base64,'$(base64 -w 0 image.jpg)'"
            }
          }
        ]
      }
    ],
    "stream": false
  }'
cURL (Windows Git Bash) 
curl -X POST "https://rozhnet.ir/wp-json/v1/chat" \
  -H "Authorization: Bearer RN-your-real-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What is in this image?"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/jpeg;base64,'$(base64 image.jpg | tr -d \"\\n\")'"
            }
          }
        ]
      }
    ],
    "stream": false
  }'
هشدار: این روش برای تصاویر بزرگ توصیه نمی‌شود زیرا payload بسیار بزرگ می‌شود و ممکن است با محدودیت‌های سرور مواجه شود.

4. Request Parameters

Parameter Type Required Description
model string Required Model ID (e.g., deepseek/deepseek-v4-flash, google/gemini-3.5-flash)
messages array Required Array of message objects with role and content
stream boolean Optional Enable streaming response (default: false)
max_tokens integer Optional Maximum tokens to generate (default: 4096)
temperature float Optional Sampling temperature (0.0 to 2.0, default: 1.0)
file_attachment file Optional File to upload (multipart/form-data only)

5. Error Handling

Common Error Codes:

HTTP Code Error Type Description
401 Unauthorized Invalid or missing API key
400 Bad Request Invalid parameters or model not found
402 Payment Required Insufficient wallet balance
403 Forbidden Access denied to this model
404 Not Found Model does not support requested input type (e.g., image with text-only model)
429 Rate Limit Too many requests, please wait
503 Service Unavailable Server busy, request queued

Error Response Example:

JSON 
{
  "success": false,
  "data": {
    "error": "Insufficient wallet balance. Please recharge your account."
  }
}

6. Best Practices

  • همیشه از HTTPS برای ارتباط با API استفاده کنید
  • کلید API خود را در متغیرهای محیطی (Environment Variables) ذخیره کنید
  • برای درخواست‌های طولانی، از streaming استفاده کنید تا تجربه کاربری بهتری داشته باشید
  • حجم فایل‌ها را قبل از آپلود بررسی کنید (حداکثر 5MB)
  • برای تصاویر، از مدل‌های Vision-Capable استفاده کنید
  • خطاهای API را به درستی مدیریت کنید و پیام‌های مناسب به کاربر نمایش دهید
  • مصرف توکن خود را از طریق پنل کاربری مانیتور کنید

7. Rate Limits & Concurrency

Global Concurrency: حداکثر 10 درخواست همزمان در سراسر سیستم

Queue System: اگر تمام slotها پر باشند، درخواست شما در صف قرار می‌گیرد (حداکثر 60 ثانیه انتظار)

Timeout: هر درخواست حداکثر 120 ثانیه زمان دارد