README.fa.md

Rahyana API - نمونه‌های PHP

این پوشه شامل نمونه‌های PHP برای استفاده از Rahyana AI API است. این نمونه‌ها نحوه ادغام قابلیت‌های هوش مصنوعی Rahyana را در برنامه‌های PHP، از جمله افزونه‌های وردپرس نشان می‌دهد.

📁 ساختار پوشه

php/
├── chat-completions/
│   ├── image-generation.php      # نمونه تولید تصویر
│   ├── image-editing.php         # نمونه ویرایش/تغییر تصویر
│   ├── WORDPRESS_INTEGRATION.md   # راهنمای ادغام وردپرس (انگلیسی)
│   └── WORDPRESS_INTEGRATION.fa.md # راهنمای ادغام وردپرس (فارسی)
├── completions/
└── models/

🚀 شروع سریع

پیش‌نیازها

• PHP 7.4 یا بالاتر
• افزونه cURL فعال
• افزونه GD فعال (برای اسکریپت ویرایش تصویر مورد نیاز است)
• کلید API Rahyana (از rahyana.ir دریافت کنید)

استفاده پایه

1. کلید API خود را تنظیم کنید (از طریق متغیر محیطی یا ویرایش اسکریپت):

   export API_KEY_OVERRIDE="your_api_key_here"

2. نمونه تولید تصویر را اجرا کنید:

   php chat-completions/image-generation.php

3. تصاویر تولید شده در پوشه chat-completions/generated-images/ ذخیره می‌شوند

📚 نمونه‌ها

تولید تصویر

فایل: chat-completions/image-generation.php

تولید تصویر با استفاده از Rahyana API. این نمونه:

• به Rahyana API متصل می‌شود
• بر اساس یک متن، تصویر تولید می‌کند
• تصویر تولید شده را در یک پوشه محلی ذخیره می‌کند

استفاده:

# استفاده از متغیر محیطی برای کلید API
export API_KEY_OVERRIDE="your_api_key_here"
php chat-completions/image-generation.php

# یا تنظیم پوشه خروجی
export OUTPUT_DIR="/path/to/output"
php chat-completions/image-generation.php

پیکربندی:

• API_KEY_OVERRIDE: کلید API شما (متغیر محیطی)
• OUTPUT_DIR: پوشه ذخیره تصاویر (پیش‌فرض: ./generated-images)
• مدل: google/gemini-3-pro-image-preview (قابل تنظیم در اسکریپت)
• متن: "a dog in a city" (قابل تنظیم در اسکریپت)

ویرایش تصویر

فایل: chat-completions/image-editing.php

ویرایش و تغییر تصاویر موجود با استفاده از Rahyana API. این نمونه:

• یک فایل تصویر را به عنوان ورودی می‌پذیرد
• تصویر را با دستورالعمل‌های تغییر به API ارسال می‌کند
• به طور خودکار تصاویر بزرگ را برای رعایت محدودیت‌های اندازه API تغییر اندازه می‌دهد
• تصویر ویرایش شده/تغییر یافته را در یک پوشه محلی ذخیره می‌کند

استفاده:

# استفاده پایه
export API_KEY_OVERRIDE="your_api_key_here"
php chat-completions/image-editing.php input.jpg "آن را شبیه یک نقاشی کن"

# مثال‌های بیشتر
php chat-completions/image-editing.php photo.png "غروب خورشید را در پس‌زمینه اضافه کن"
php chat-completions/image-editing.php image.jpg "پس‌زمینه را حذف کن"
php chat-completions/image-editing.php picture.png "رنگ‌ها و کنتراست را بهبود بده"

# تنظیم پوشه خروجی سفارشی
export OUTPUT_DIR="/path/to/output"
php chat-completions/image-editing.php input.jpg "آن را به سبک وینتیج کن"

ویژگی‌ها:

• تغییر اندازه خودکار تصویر برای فایل‌های بزرگ (محدودیت‌های اندازه API)
• پشتیبانی از فرمت‌های JPEG، PNG، GIF، WebP
• حفظ نسبت تصویر در هنگام تغییر اندازه
• رمزگذاری Base64 برای انتقال API
• مدیریت جامع خطا

پیکربندی:

• API_KEY_OVERRIDE: کلید API شما (متغیر محیطی)
• OUTPUT_DIR: پوشه ذخیره تصاویر ویرایش شده (پیش‌فرض: ./edited-images)
• مدل: google/gemini-3-pro-image-preview (قابل تنظیم در اسکریپت)
• متن تغییر: به عنوان آرگومان خط فرمان ارائه می‌شود

🔌 ادغام وردپرس

فایل‌ها:

• chat-completions/WORDPRESS_INTEGRATION.md (انگلیسی)
• chat-completions/WORDPRESS_INTEGRATION.fa.md (فارسی)

راهنمای کامل برای ادغام تولید تصویر Rahyana در وردپرس:

• ✅ ایجاد افزونه مستقل
• ✅ پیاده‌سازی شورتکد
• ✅ توسعه بلاک گوتنبرگ
• ✅ بهترین روش‌های امنیتی
• ✅ مدیریت خطا
• ✅ استراتژی‌های کش

ادغام سریع وردپرس

1. یک پوشه افزونه ایجاد کنید در wp-content/plugins/
2. کد ادغام را کپی کنید از WORDPRESS_INTEGRATION.md
3. کلید API خود را پیکربندی کنید در تنظیمات وردپرس
4. از شورتکد استفاده کنید در پست‌ها/صفحات:

   [rahyana_image prompt="a dog in a city" size="large"]
   

🛠️ ویژگی‌ها

اسکریپت تولید تصویر

• ✅ ادغام کامل API با Rahyana
• ✅ مدیریت چندین فرمت پاسخ
• ✅ استخراج و رمزگشایی تصویر base64
• ✅ ایجاد خودکار پوشه
• ✅ مدیریت جامع خطا
• ✅ رابط خط فرمان

اسکریپت ویرایش تصویر

• ✅ فایل‌های تصویر را به عنوان ورودی می‌پذیرد
• ✅ تغییر اندازه خودکار تصویر برای فایل‌های بزرگ
• ✅ پشتیبانی از چندین فرمت تصویر (JPEG، PNG، GIF، WebP)
• ✅ رمزگذاری Base64 برای انتقال API
• ✅ تغییر تصویر با متن‌های سفارشی
• ✅ حفظ نسبت تصویر در هنگام تغییر اندازه
• ✅ پاکسازی فایل‌های موقت

ادغام وردپرس

• ✅ صفحه تنظیمات ادمین
• ✅ پشتیبانی از شورتکد
• ✅ ادغام با کتابخانه رسانه
• ✅ بهترین روش‌های امنیتی
• ✅ پشتیبانی از کش
• ✅ مدیریت خطا

📖 مرجع API

درخواست تولید تصویر

$data = [
    'model' => 'google/gemini-3-pro-image-preview',
    'messages' => [
        [
            'role' => 'user',
            'content' => 'متن شما اینجا'
        ]
    ],
    'modalities' => ['image', 'text']
];

ساختار پاسخ

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

• providerResponse.choices[0].message.images[0].image_url.url
• choices[0].message.content (آرایه یا رشته)
• URLهای داده مستقیم

🔒 امنیت

• هرگز کلیدهای API را در کنترل نسخه commit نکنید
• از متغیرهای محیطی برای کلیدهای API استفاده کنید
• تمام ورودی‌های کاربر را sanitize کنید
• پاسخ‌های API را اعتبارسنجی کنید
• از nonceهای وردپرس برای درخواست‌های AJAX استفاده کنید

🐛 عیب‌یابی

مشکلات رایج

1. "کلید API پیکربندی نشده"

   • متغیر محیطی API_KEY_OVERRIDE را تنظیم کنید
   • یا اسکریپت را با کلید API خود به‌روزرسانی کنید

2. "ایجاد پوشه ناموفق بود"

   • مجوزهای پوشه را بررسی کنید
   • اطمینان حاصل کنید که PHP دسترسی نوشتن دارد

3. "هیچ تصویری در پاسخ یافت نشد"

   • ساختار پاسخ API را بررسی کنید
   • تأیید کنید که مدل از تولید تصویر پشتیبانی می‌کند
   • مجوزهای کلید API را بررسی کنید

4. وردپرس: "کلید API پیکربندی نشده"

   • به Settings > Rahyana Image Generator بروید
   • کلید API خود را وارد کنید

📝 نمونه‌های کد

تولید تصویر پایه

<?php
require_once 'class-rahyana-image-generator.php';

$api_key = 'your_api_key_here';
$generator = new Rahyana_Image_Generator($api_key);

$result = $generator->generate_image('a dog in a city');

if (is_wp_error($result)) {
    echo 'خطا: ' . $result->get_error_message();
} else {
    echo 'URL تصویر: ' . $result['image_url'];
}

شورتکد وردپرس

[rahyana_image prompt="غروب زیبای خورشید بر فراز کوه‌ها" size="large" class="my-custom-class"]

🔗 منابع مرتبط

• مستندات Rahyana API
• راهنمای افزونه وردپرس
• مستندات PHP cURL

📄 مجوز

این نمونه‌ها به‌صورت "همان‌طور که هستند" برای اهداف آموزشی و ادغام ارائه می‌شوند.

🤝 مشارکت

مشارکت‌ها خوش‌آمد هستند! لطفاً:

1. از استانداردهای کدنویسی PHP (PSR-12) پیروی کنید
2. مدیریت خطا را شامل شوید
3. برای منطق پیچیده نظر اضافه کنید
4. با کلیدهای API واقعی (با امنیت) تست کنید

📧 پشتیبانی

برای مشکلات یا سوالات:

• راهنمای ادغام وردپرس را بررسی کنید
• مستندات API را در rahyana.ir/docs مرور کنید
• یک issue در GitHub باز کنید