Threedify · مستندات API

۱معرفی و احراز هویت

تمام درخواست‌های API باید از طریق HTTPS ارسال شوند و شامل token احراز هویت در header باشند. token ها با JWT امضا شده و اعتبار ۲۴ ساعته دارند.

Base URL: https://api.threedify.ai/v1

POST/auth/login

ورود با شماره موبایل و دریافت access token

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

نام	نوع	اجباری	توضیح
phone	string	بله	شماره موبایل با فرمت بین‌المللی (مثال: +989123456789)
otp_code	string	بله	کد تأیید ۶ رقمی ارسال شده به موبایل

نمونه درخواست:

{
  "phone": "+989123456789",
  "otp_code": "123456"
}

پاسخ موفق:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "user_id": "usr_abc123def456"
}

POST/auth/send-otp

ارسال کد تأیید به شماره موبایل

POST /auth/send-otp
{
  "phone": "+989123456789"
}

۲مدیریت کاربر

GET/users/me

دریافت اطلاعات کاربر فعلی

Headers:

Authorization: Bearer <access_token>

پاسخ:

{
  "id": "usr_abc123def456",
  "phone": "+989123456789",
  "email": "user@example.com",
  "display_name": "کاربر Threedify",
  "credits_balance": 150,
  "created_at": "2026-01-15T10:30:00Z"
}

PUT/users/me

به‌روزرسانی اطلاعات کاربر

PUT /users/me
{
  "email": "newemail@example.com",
  "display_name": "نام جدید"
}

DELETE/users/me

حذف کامل حساب کاربر (غیرقابل بازگشت)

این عملیات غیرقابل بازگشت است. تمام داده‌های کاربر ظرف ۲۴ ساعت حذف خواهند شد.

DELETE /users/me
Authorization: Bearer <access_token>

۳پردازش درخواست‌ها

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

POST/requests

ایجاد درخواست جدید برای پردازش توسط مدل AI

پارامترها:

نام	نوع	اجباری	توضیح
model	string	بله	شناسه مدل (مثال: gpt-4, dall-e-3, stable-diffusion)
input	string	بله	متن ورودی یا prompt
attachments	array	خیر	لیست فایل‌های ضمیمه (حداکثر ۵ فایل، هر کدام حداکثر ۱۰MB)
parameters	object	خیر	پارامترهای اختصاصی مدل (temperature, max_tokens, etc.)

نمونه درخواست:

{
  "model": "gpt-4",
  "input": "یک داستان کوتاه درباره هوش مصنوعی بنویس",
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 500
  }
}

پاسخ:

{
  "request_id": "req_xyz789",
  "status": "processing",
  "model": "gpt-4",
  "credits_used": 5,
  "created_at": "2026-09-07T14:30:00Z",
  "expires_at": "2026-09-08T14:30:00Z"
}

GET/requests/{request_id}

دریافت وضعیت و نتیجه یک درخواست

GET /requests/req_xyz789
Authorization: Bearer <access_token>

پاسخ:

{
  "request_id": "req_xyz789",
  "status": "completed",
  "model": "gpt-4",
  "output": {
    "text": "روزی روزگاری، در شهری مدرن...",
    "tokens_used": 487
  },
  "created_at": "2026-09-07T14:30:00Z",
  "completed_at": "2026-09-07T14:30:15Z",
  "expires_at": "2026-09-08T14:30:00Z"
}

DELETE/requests/{request_id}

حذف فوری یک درخواست (قبل از حذف خودکار ۲۴ ساعته)

DELETE /requests/req_xyz789
Authorization: Bearer <access_token>

۴مدیریت اعتبار

GET/credits/balance

دریافت موجودی اعتبار فعلی

{
  "balance": 150,
  "currency": "credits",
  "last_updated": "2026-09-07T14:30:00Z"
}

GET/credits/transactions

دریافت تاریخچه تراکنش‌های اعتبار

Query Parameters:

نام	نوع	توضیح
limit	integer	تعداد نتایج (پیش‌فرض: 20، حداکثر: 100)
offset	integer	شروع از (برای pagination)

{
  "transactions": [
    {
      "id": "txn_abc123",
      "type": "purchase",
      "amount": 100,
      "description": "خرید بسته ۱۰۰ اعتباری",
      "created_at": "2026-09-01T10:00:00Z"
    },
    {
      "id": "txn_def456",
      "type": "usage",
      "amount": -5,
      "description": "پردازش درخواست با GPT-4",
      "request_id": "req_xyz789",
      "created_at": "2026-09-07T14:30:15Z"
    }
  ],
  "total": 45
}

GET/credits/export

دانلود تاریخچه کامل تراکنش‌ها در قالب JSON (حق قابل‌حمل بودن داده)

GET /credits/export
Authorization: Bearer <access_token>

// پاسخ: فایل JSON با تمام تراکنش‌ها

۵حریم خصوصی و داده‌ها

GET/privacy/data-export

دریافت کپی از تمام داده‌های ذخیره‌شده (حق دسترسی)

{
  "user_data": {
    "profile": {...},
    "transactions": [...],
    "requests_history": [...]
  },
  "exported_at": "2026-09-07T15:00:00Z"
}

POST/privacy/anonymize

درخواست ناشناس‌سازی داده‌ها (حفظ حساب اما حذف اطلاعات شخصی)

این عملیات غیرقابل بازگشت است. اطلاعات شخصی حذف می‌شود اما حساب و اعتبار باقی می‌ماند.

POST/privacy/dpo-contact

ارسال درخواست یا شکایت به مسئول حفاظت از داده (DPO)

{
  "subject": "درخواست دسترسی به داده‌ها",
  "message": "می‌خواهم کپی کامل داده‌هایم را دریافت کنم...",
  "contact_email": "user@example.com"
}

۶کدهای وضعیت HTTP

کد	معنی	توضیح
200	موفق	درخواست با موفقیت پردازش شد
201	ایجاد شد	منبع جدید با موفقیت ایجاد شد
400	درخواست نامعتبر	پارامترهای درخواست ناقص یا نادرست هستند
401	غیرمجاز	Token احراز هویت نامعتبر یا منقضی شده
403	ممنوع	دسترسی به این منبع مجاز نیست
404	یافت نشد	منبع درخواستی وجود ندارد
429	تعداد درخواست بیش از حد	Rate limit exceeded - لطفاً صبر کنید
500	خطای سرور	خطای داخلی سرور - تیم فنی مطلع شده است

فرمت پاسخ خطا:

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Token احراز هویت نامعتبر یا منقضی شده است",
    "details": "لطفاً مجدداً وارد شوید"
  }
}

۷محدودیت‌ها و Rate Limiting

برای حفظ کیفیت سرویس و امنیت، محدودیت‌های زیر اعمال می‌شود:

محدودیت	مقدار	توضیح
درخواست‌ها در دقیقه	۱۰۰	برای هر کاربر
اندازه فایل ضمیمه	۱۰MB	حداکثر برای هر فایل
تعداد فایل‌های ضمیمه	۵	حداکثر در هر درخواست
طول متن ورودی	۱۰,۰۰۰ کاراکتر	حداکثر برای هر درخواست
اعتبار Token	۲۴ ساعت	پس از آن نیاز به ورود مجدد
نگهداری درخواست‌ها	۲۴ ساعت	حذف خودکار پس از پردازش

Headers مربوط به Rate Limit:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1694095200

۸نمونه کد

Python:

import requests

BASE_URL = "https://api.threedify.ai/v1"
TOKEN = "your_access_token_here"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# ایجاد درخواست جدید
response = requests.post(
    f"{BASE_URL}/requests",
    headers=headers,
    json={
        "model": "gpt-4",
        "input": "یک داستان کوتاه بنویس",
        "parameters": {"temperature": 0.7}
    }
)

request_data = response.json()
print(f"Request ID: {request_data['request_id']}")

JavaScript (Node.js):

const axios = require('axios');

const BASE_URL = 'https://api.threedify.ai/v1';
const TOKEN = 'your_access_token_here';

const headers = {
  'Authorization': `Bearer ${TOKEN}`,
  'Content-Type': 'application/json'
};

// دریافت موجودی اعتبار
axios.get(`${BASE_URL}/credits/balance`, { headers })
  .then(response => {
    console.log(`موجودی: ${response.data.balance}`);
  })
  .catch(error => {
    console.error('Error:', error.response.data);
  });

cURL:

# ورود و دریافت token
curl -X POST https://api.threedify.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"phone": "+989123456789", "otp_code": "123456"}'

# ایجاد درخواست
curl -X POST https://api.threedify.ai/v1/requests \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "input": "Hello"}'

برای اطلاعات بیشتر یا پشتیبانی، با تیم فنی ما در api-support@threedify.ai تماس بگیرید.