💻 مثال ساده از درخواست و پاسخ API تشخیص احساسات متن

با یک درخواست ساده به endpoint سرویس (مثلاً /sentiment)، می‌توانید متن را ارسال و نتیجه را به‌صورت JSON دریافت کنید:

curl -X POST https://api.example.com/sentiment \
-H "Authorization: Bearer {API_KEY}" \
-d '{"text": "این محصول واقعاً عالی بود و تجربه فوق‌العاده‌ای داشتم"}'
      

نمونه پاسخ JSON قابل بازگشت:

{
  "sentiment": "positive",
  "confidence": 0.97
}
      

🔒 امنیت و اطمینان در استفاده از API

تبادل داده‌ها با کلید API اختصاصی و پروتکل‌های رمزنگاری انجام می‌شود تا اطلاعات شما محرمانه و تراکنش‌ها قابل اطمینان باشند. تمام درخواست‌ها از طریق HTTPS ارسال و دریافت شده و سرورهای سرویس معمولاً حداکثر پایداری را ارائه می‌کنند.

🔍 نمونه خروجی JSON API احساسات

{
  "status": "success",
  "sentiment": "مثبت",
  "confidence": 0.92,
  "input_text": "این یک متن نمونه است.",
  "details": {
    "positive": 0.92,
    "neutral": 0.06,
    "negative": 0.02
  },
  "language": "fa"
}
    

این خروجی استاندارد بسیاری از سرویس‌های تشخیص احساسات API با ساختار JSON است که اطلاعات کلیدی تحلیل شده را در اختیار توسعه‌دهنده قرار می‌دهد.

🗂️ نکات کلیدی ساختار

• فیلدهای status، sentiment و confidence معمولا اجباری و همیشه در پاسخ بازگشتی API قرار می‌گیرند.
• فیلد details یک شیء (object) شامل احتمال هر نوع احساس است و برای تحلیل عمیق‌تر مفید خواهد بود.
• در صورت بروز خطا یا عدم موفقیت، مقدار status به ’error‘ تغییر می‌کند و معمولا فیلد message یا error_code نیز افزوده می‌شود:

{
  "status": "error",
  "message": "API Key is invalid.",
  "error_code": 401
}

💻 نمونه کد خواندن پاسخ JSON در پایتون

import requests
API_URL = "https://your-ai-api.com/sentiment"
payload = {"text": "این یک تست است"}
response = requests.post(API_URL, json=payload)
data = response.json()
print("Sentiment:", data["sentiment"])
print("Confidence:", data["confidence"])
    

این مثال ساده نحوه استخراج مقادیر احساسات را از فرمت JSON بازگشتی API هوش مصنوعی نشان می‌دهد. استفاده از .get() برای کنترل Null و مدیریت خطا توصیه می‌شود.

🎯 نکات مهم در استفاده از ساختار داده API

• قبل از استفاده از فیلدهای بازگشتی، وجود هر کلید را چک کنید تا برنامه به خطا نخورد.
• برای اطمینان از مطابقت خروجی با مستندات، می‌توانید JSON Schema Validation یا کتابخانه‌هایی مانند Pydantic و Marshmallow را به‌کار گیرید.
• در پروژه‌هایی با نیاز به خروجی زنده و سریع، صرفاً فقط فیلدهایی که لازم دارید را از JSON استخراج کنید تا پردازش بهینه باشد.
• در صورت نیاز به پیاده‌سازی سناریوهای عملی، بخش جزئیات نمونه کد پیاده‌سازی Request و Response برای توسعه‌دهندگان نیز مناسب مطالعه بیشتر است.

📚 راهنمای سریع زبان‌های پشتیبانی‌شده برای نمونه‌کدهای API

POST https://api.example.com/sentiment
Headers:
    Authorization: Bearer {API_KEY}
    Content-Type: application/json
Body:
    {"text": "این محصول عالی است"}
    

{
  "sentiment": "positive",
  "confidence": 0.97
}
    

👨‍💻 Python (کتابخانه requests)

import requests
url = "https://api.example.com/sentiment"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "text": "تجربه کاربری این سایت بسیار عالی بود!"
}
response = requests.post(url, json=data, headers=headers)
مدیریت پاسخ و بررسی خروجی
if response.status_code == 200:
    result = response.json()
    print("برچسب احساس:", result['sentiment'])
    print("ضریب اطمینان:", result['confidence'])
else:
    print("خطا:", response.text)
    

نکته: مقدار YOUR_API_KEY را با کلید دریافت‌شده جایگزین کنید.

🌐 JavaScript (Node.js با axios)

const axios = require("axios");
const url = "https://api.example.com/sentiment";
const apiKey = "YOUR_API_KEY";
axios.post(url, {
    text: "پشتیبانی آنی این سرویس خیلی عالی بود!"
}, {
    headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json"
    }
}).then(response => {
    const data = response.data;
    console.log("نوع احساس:", data.sentiment);
    console.log("Confidence:", data.confidence);
}).catch(error => {
    console.error("خطا در API:", error.response ? error.response.data : error.message);
});
    

این قطعه کد برای انواع پروژه‌های Express/React/Next.js به سادگی قابل سفارشی‌سازی است.

☕ Java (HttpURLConnection نمونه ساده)

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.util.Scanner;
String apiKey = "YOUR_API_KEY";
String text = "محصول بسیار کاربردی است!";
URL url = new URL("https://api.example.com/sentiment");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Authorization", "Bearer " + apiKey);
conn.setRequestProperty("Content-Type", "application/json");
conn.setDoOutput(true);
String jsonInput = "{\"text\": \"" + text + "\"}";
try(OutputStream os = conn.getOutputStream()) {
    os.write(jsonInput.getBytes("UTF-8"));
}
Scanner sc = new Scanner(conn.getInputStream());
while(sc.hasNext()) {
    System.out.println(sc.nextLine());
}
sc.close();
    

برای Android نیز می‌توانید از Retrofit/OkHttp به راحتی استفاده کنید.

🐘 PHP (cURL)

<?php
$url = "https://api.example.com/sentiment";
$apiKey = "YOUR_API_KEY";
$data = array("text" => "رابط کاربری برای من رضایت‌بخش بود");
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Authorization: Bearer $apiKey",
    "Content-Type: application/json"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$result = curl_exec($ch);
curl_close($ch);
$response = json_decode($result, true);
echo "برچسب احساس: " . $response["sentiment"] . "<br>";
echo "Confidence: " . $response["confidence"];
?>
    

سازگار با انواع فریم‌ورک‌های PHP مانند Laravel، WordPress و سایر پروژه‌ها.

🔗 cURL (کامن‌لاین لینوکس/ویندوز/مک)

curl -X POST https://api.example.com/sentiment \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "روند پاسخگویی سریع و عالی بود"}'
    

آسان‌ترین روش تست API هوش مصنوعی قبل از پیاده‌سازی نهایی.

⚠️ مدیریت خطا و محدودیت‌های API هوش مصنوعی

• خطای 401 Unauthorized: کلید API اشتباه یا نامعتبر. صحت کلید را بررسی کنید.
• خطای 429 Too Many Requests: به محدودیت نرخ درخواست رسیده‌اید. حتماً سویچ backoff/Retry را در برنامه لحاظ کنید.
• خطای 500 Internal Server Error: مشکل سمت سرویس. دقایقی بعد مجدداً تلاش کنید.

📡 اطلاعات ساختاری درخواست

• URL کامل: https://api.example.com/v1/sentiment
• HTTP Method: POST
• Headers:
  • Authorization: Bearer {API_KEY}
  • Content-Type: application/json; charset=utf-8
• Body:

  {
    "text": "از خدمات شما کاملاً رضایت دارم."
  }

💻 نمونه کد پایتون (Python Requests)

import requests
url = "https://api.example.com/v1/sentiment"
api_key = "YOUR_API_KEY"
text = "این تجربه برای من خیلی عالی بود — حتما پیشنهاد می‌کنم."
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json; charset=utf-8"
}
payload = {"text": text}
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
    print(response.json())  # {'sentiment': 'positive', 'confidence': 0.92}
else:
    print("Error:", response.status_code)
    

💻 نمونه کد جاوااسکریپت (Node.js + Axios)

const axios = require('axios');
axios.post("https://api.example.com/v1/sentiment", 
    { text: "محصول خیلی خوب و پشتیبانی عالی!" },
    {
        headers: {
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json; charset=utf-8"
        }
    }
)
.then(res => {
    // res.data: { sentiment: "positive", confidence: 0.89 }
    console.log(res.data);
})
.catch(e => {
    if(e.response){
        console.log("Error:", e.response.status);
    } else {
        console.log("Network or connection error");
    }
});
    

💻 نمونه کد PHP (CURL)

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.example.com/v1/sentiment");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["text" => "پاسخگویی سریع و حرفه‌ای!"]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json; charset=utf-8"
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response; // {"sentiment": "positive", "confidence": 0.91}
    

🔗 مثال درخواست HTTP

⚠️ نکات طلایی مدیریت خطا

• قبل از Log خطا، حتما مقدار status code را بررسی و لایه شبکه (timeout، تحریم و ...) را جداگانه رصد کنید
• در صورت مواجهه با 401، ابتدا کلید API و سپس اعتبار دامنه را کنترل کنید
• برای خطاهای 429 و Rate limit، از Retry با backoff تصادفی (exponential) استفاده نمایید
• هر پاسخ غیر-200 را در سمت کلاینت log و ذخیره کنید تا هنگام رفع ایراد، دیتای کافی داشته باشید

⚡ نمونه پروژه: تشخیص احساس هر کامنت سایت

def analyze_comment_list(comment_list):
    url = "https://api.example.com/v1/sentiment"
    api_key = "YOUR_API_KEY"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json; charset=utf-8"
    }
    results = []
    for comment in comment_list:
        data = {"text": comment}
        resp = requests.post(url, json=data, headers=headers)
        if resp.status_code == 200:
            res = resp.json()
            print(f"نظر: {comment}\nاحساس: {res['sentiment']} (اعتماد: {res['confidence']})")
            results.append(res)
        else:
            print(f"خطا در نظر: {comment}, Status: {resp.status_code}")
    return results
comments = [
    "پشتیبانی شما واقعاً عالی بود.",
    "زمان ارسال خیلی طول کشید!",
    "خدمات معمولی و قابل قبول."
]
analyze_comment_list(comments)
    

⚖️ اطلاع‌رسانی حقوقی و اخلاقی

مسئولیت استفاده از تحریم‌شکن API و عبور از تحریم‌ها با رعایت قوانین داخلی و بین‌المللی بر عهده توسعه‌دهنده/شرکت استفاده‌کننده است. شفافیت و مسئولیت‌پذیری را در کاربرد API مدنظر قرار دهید.

💻 نمونه کد درخواست با پروکسی (Python)

import requests
proxies = {
  "https": "http://your-tahirim-shekan-ip:port",
  "http":  "http://your-tahirim-shekan-ip:port"
}
response = requests.post(
  "https://ai-sentiment-api.com/v1/analyze",
  json={"text": "من عالی هستم!"},
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  proxies=proxies
)
print(response.json())
    

این مثال، ارسال درخواست API هوش مصنوعی تشخیص احساسات از طریق یک تحریم‌شکن اختصاصی را نشان می‌دهد.

⚠️ محدودیت‌ها

اکثر APIهای هوش مصنوعی تشخیص احساسات محدودیت نرخ درخواست (Rate Limit) دارند. معمولاً برای کلید رایگان، مثلاً ۵۰ درخواست در دقیقه و برای پلن‌های تجاری، سقف بالاتری تعیین می‌شود.
بهترین راه: وضعیت خطای 429 Too Many Requests را مدیریت کنید و پس از رخداد، تاخیر دیتا (Retry with Backoff) قرار دهید.
برای جزئیات بیشتر درباره پلن‌ها و تفاوت رایگان/تجاری به خرید api هوش مصنوعی مراجعه کنید.

💻 مثال کد مدیریت خطا (پایتون)

import time, requests
for attempt in range(3):
    resp = requests.post(url, json=payload, headers=headers)
    if resp.status_code == 200:
        print(resp.json())
        break
    elif resp.status_code == 429:
        time.sleep(2 ** attempt)  # backoff
    else:
        print("Error:", resp.status_code)
    

کد را طوری بنویسید که وضعیت‌های 401, 429, 500 را هندل کند.

سایر زبان‌ها (Go, Ruby, C#) نیز با ارسال درخواست HTTP قابل استفاده‌اند.

برخی سرویس‌دهندگان خارجی محدودیت دسترسی برای IPهای ایران دارند. راهکار عبارت است از:

• استفاده از تحریم‌شکن مطمئن برای سرور (مثل tunnel امن یا وکلای بین‌المللی مجاز)
• انتخاب سرویس‌هایی با پشتیبانی رسمی ایران یا گزینه‌هایی که برای کاربران ایرانی باز است
• درصورت مشکل، ارسال درخواست از سروری خارج از محدوده تحریم، سپس ری‌دایرکت به سرور داخلی

جلوگیری از افشای کلید API ضروری است!

💻 نمونه کد ساده (Python)

res = {"sentiment":"positive","confidence":0.94}
print(res['sentiment'], res['confidence'])

مقدار sentiment یکی از: positive, negative, neutral است. عدد confidence میزان اطمینان مدل (۰ تا ۱) است.

⚡ عملکرد

بسیاری از سرویس‌ها endpoint /v1/sentiment/batch دارند و ورودی به شکل:

{
  "texts": ["نظرت عالی بود.", "کیفیت بد بود.", "سریع و خوب!"]
}

[
  {"sentiment":"positive", "confidence":0.93},
  {"sentiment":"negative", "confidence":0.88},
  {"sentiment":"positive", "confidence":0.95}
]

حتماً از ارتباط HTTPS استفاده کنید. بسیاری از سرویس‌ها رمزنگاری در لایه انتقال و محدودیت دسترسی کلید را تضمین می‌کنند.
کلید API خود را فقط در بک‌اند و سرور نگه دارید و هرگز در کد سمت کلاینت (React/Vue) قرار ندهید.

راهنمای عملی‌تر: امنیت ارتباط با ای پی آی‌های هوش مصنوعی

اکثر ارائه‌دهندگان، طرح رایگان محدود یا Sandbox (با محدودیت نرخ و متن کوتاه) برای تست کد و آشنایی با API دارند.
جزئیات و محدودیت‌ها در بخش api های رایگان هوش مصنوعی موجود است.