مستندات API

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

Authorization: Bearer pf_live_xxxxxxxxxxxxxxxx

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

• هر کاربر حداکثر ۱۰ کلید فعال
• کلید کامل فقط یک‌بار هنگام ساخت نمایش داده می‌شود
• کلید لغو‌شده دیگر کار نمی‌کند

POST https://pintfa.com/api/v1/extract

با این endpoint متادیتا و لیست media یک پین را دریافت می‌کنید.

{
  "url": "https://www.pinterest.com/pin/1234567890/"
}

ورودی‌های مجاز برای فیلد url:

• https://www.pinterest.com/pin/ID/
• https://pin.it/xxxx
• 1234567890 (شناسه عددی)

curl -X POST https://pintfa.com/api/v1/extract \
  -H "Authorization: Bearer pf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://pin.it/example"}'

GET https://pintfa.com/api/v1/proxy

فایل media را از CDN پینترست (pinimg.com) دانلود می‌کند. فقط URLهای pinimg مجازند.

GET https://pintfa.com/api/v1/proxy?url=https%3A%2F%2Fi.pinimg.com%2F...&pin=1234567890
Authorization: Bearer pf_live_YOUR_KEY

• url — آدرس encode‌شده فایل pinimg
• pin — اختیاری — برای آمار دانلود

GET https://pintfa.com/api/v1/health

اعتبار کلید و اطلاعات پایه سرویس را برمی‌گرداند.

{
  "success": true,
  "data": {
    "service": "pintfa",
    "version": "1",
    "key": { "id": "...", "name": "My App", "prefix": "pf_live_abc…" }
  }
}

پاسخ موفق extract شامل اطلاعات پین و آرایه media است:

{
  "success": true,
  "data": {
    "id": "1234567890",
    "title": "عنوان پین",
    "description": "...",
    "author": "username",
    "contentType": "video",
    "thumbnail": "https://i.pinimg.com/...",
    "sourceUrl": "https://www.pinterest.com/pin/...",
    "media": [
      {
        "type": "video",
        "url": "https://v1.pinimg.com/...",
        "label": "HD",
        "quality": "hd",
        "width": 1080,
        "height": 1920
      }
    ]
  }
}

مقادیر contentType:

• image
• video
• gif
• carousel
• idea_pin
• mixed

• extract: حداکثر ۶۰ درخواست در دقیقه و ۵۰۰ درخواست در روز (به ازای هر کلید)
• proxy: حداکثر ۱۲۰ درخواست در دقیقه و ۲۰۰۰ درخواست در روز (به ازای هر کلید)
• فایل‌ها تا ۷ روز روی سرور پینتفا cache می‌شوند — پاسخ extract تا ۱ ساعت cache می‌شود
• API عمومی محدودیت IP دارد؛ فایل‌های media از pintfa.com سرو می‌شوند و در ایندکس گوگل نیستند

JavaScript (fetch)

const res = await fetch('https://pintfa.com/api/v1/extract', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer pf_live_YOUR_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://pin.it/example' }),
});
const json = await res.json();
if (json.success) console.log(json.data.media);

Python (requests)

import requests

r = requests.post(
    'https://pintfa.com/api/v1/extract',
    headers={'Authorization': 'Bearer pf_live_YOUR_KEY'},
    json={'url': 'https://pin.it/example'},
    timeout=30,
)
data = r.json()
print(data['data']['media'] if data.get('success') else data)

PHP

$ch = curl_init('https://pintfa.com/api/v1/extract');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer pf_live_YOUR_KEY',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode(['url' => 'https://pin.it/example']),
  CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
curl_close($ch);
echo $body;