تبدیل متن فارسی به فینگلیش
یک API ساده برای دریافت واژه یا عبارت فارسی و برگرداندن نگارش فینگلیش استاندارد آن. ارتباط از طریق JSON و احراز هویت با API Key انجام میشود.
POST
https://api.varse.ir/utils/persian-to-finglish
احراز هویت
کلید اختصاصی سرویس باید در هدر هر درخواست ارسال شود.
نام هدر
X-API-Keyاین هدر برای تمام درخواستها اجباری است.
نوع محتوا
application/jsonبدنهٔ درخواست باید JSON معتبر باشد.
نکتهٔ امنیتیAPI Key را در کد سمت مرورگر، مخزن عمومی یا فایل قابل دانلود قرار ندهید. درخواست را ترجیحاً از backend خودتان ارسال کنید.
شروع سریع
مقدار YOUR_API_KEY را با کلید دریافتی جایگزین کنید.
cURL
curl --location 'https://api.varse.ir/utils/persian-to-finglish' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data '{
"word": "سعید"
}'
ساختار درخواست
درخواست فقط یک فیلد اجباری دارد.
| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
word | string | بله | واژه یا عبارت فارسی؛ حداکثر ۲۰۰ نویسه و شامل حداقل یک نویسهٔ فارسی. |
Request body
{
"word": "سعید"
}
پاسخ موفق
در پاسخ موفق، کلمهٔ پردازششده و معادل فینگلیش آن برگردانده میشود.
HTTP 200 · JSON
{
"word": "سعید",
"finglish": "saeed"
}
| فیلد | نوع | توضیح |
|---|---|---|
word | string | متن فارسی پردازششده. |
finglish | string | نتیجهٔ تبدیلشده به فینگلیش. |
نمونههای پیادهسازی
در محیط production کلید را از متغیر محیطی یا Secret Manager بخوانید.
JavaScript · fetch
const response = await fetch(
'https://api.varse.ir/utils/persian-to-finglish',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': process.env.VARSE_API_KEY,
},
body: JSON.stringify({ word: 'سعید' }),
}
);
if (!response.ok) {
throw new Error(`Varse API failed: ${response.status}`);
}
const result = await response.json();
console.log(result.finglish);
PHP · cURL
$request = curl_init(
'https://api.varse.ir/utils/persian-to-finglish'
);
curl_setopt_array($request, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-Key: ' . getenv('VARSE_API_KEY'),
],
CURLOPT_POSTFIELDS => json_encode(
['word' => 'سعید'],
JSON_UNESCAPED_UNICODE
),
]);
$body = curl_exec($request);
$status = curl_getinfo($request, CURLINFO_HTTP_CODE);
curl_close($request);
if ($status !== 200 || $body === false) {
throw new RuntimeException('Varse API request failed.');
}
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
Python · requests
import os
import requests
response = requests.post(
'https://api.varse.ir/utils/persian-to-finglish',
headers={
'X-API-Key': os.environ['VARSE_API_KEY'],
},
json={'word': 'سعید'},
timeout=30,
)
response.raise_for_status()
result = response.json()
print(result['finglish'])
کدهای خطا
برای تمام پاسخهای ناموفق، وضعیت HTTP را بررسی کنید و متن خطا را log کنید.
| وضعیت | معنا | راهکار |
|---|---|---|
| 400 | JSON نامعتبر | ساختار بدنهٔ درخواست را بررسی کنید. |
| 401 | API Key نامعتبر یا خالی | هدر X-API-Key را بررسی کنید. |
| 405 | متد نامعتبر | درخواست را فقط با POST ارسال کنید. |
| 415 | Content-Type نامعتبر | از application/json استفاده کنید. |
| 422 | ورودی نامعتبر یا غیرقابل تبدیل | مقدار word و محدودیت طول را بررسی کنید. |
| 429 | عبور از سقف روزانه | تا بازنشانی سهمیه صبر کنید یا سقف را افزایش دهید. |
| 500 | خطای داخلی سرویس | درخواست را با backoff محدود تکرار و خطا را گزارش کنید. |
Error response
{
"error": {
"status": 401,
"message": "A valid X-API-Key header is required."
}
}