---
title: "مستند جامع لوما"
version: "1.4"
status: "public"
language: "fa"
---

# مستند جامع لوما (LUMA)

> **بازبینی محصول:** ۱۵ مهر ۱۴۰۵ (۷ اکتبر ۲۰۲۶). قابلیت‌ها و مدل‌های متغیر با وضعیت کد محصول در شاخهٔ `main` تا ۶ اکتبر ۲۰۲۶ تطبیق داده شده‌اند. قیمت یا دسترسی‌ای که در حساب کاربر نمایش داده می‌شود، برای همان درخواست ملاک است.

این سند مرجع شناخت محصول برای تیم‌های محصول، فروش، پشتیبانی و محتواست؛ جایگزین شرایط استفاده یا سیاست حریم خصوصی نیست. در تعارض با اسناد حقوقی جاری، اسناد حقوقی ملاک‌اند.

## راهنمای خواندن و منابع معتبر

در پاسخ‌گویی، این سه وضعیت را با هم یکی نگیرید:

- **وضعیت زندهٔ محصول:** رفتار، ابزار، مدل و هزینه‌ای که اکنون در داشبورد یا API قابل استفاده و نمایش است.
- **طرح مصوب:** سیاست یا پلنی که در سند مصوب ثبت شده؛ وجود آن به‌تنهایی به معنی فعال‌بودن در محصول نیست.
- **برنامهٔ آینده:** قابلیت یا تغییر تجاری‌ای که هنوز در رابط قابل خرید یا استفاده نشده است.

ترتیب رجوع برای اطلاعات متغیر:

1. ابزار، مدل، مسیر و هزینهٔ جاری: داشبورد و پیاده‌سازی فعلی محصول؛
2. پلن‌های مصوب و سیاست اشتراک: [طرح‌های اشتراکی مصوب لوما](Subscription-plan.md)، با بررسی وضعیت اجرای زنده؛
3. منبع مرجع جزئیات قیمت هر مدل: فایل داخلی `knowledge/internal/pricing/Luma Pricing - Pricing.csv`؛ [جدول تفصیلی عمومی قیمت‌گذاری](pricing.md) یک snapshot ناهمگام است و منبع قیمت جاری نیست؛
4. واقعیت‌های پایهٔ شرکت و محصول: همین سند، مگر آنکه منبع جدیدتر و معتبرتری وجود داشته باشد.

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

## فهرست

1. [لوما چیست؟](#۱-لوما-چیست)
2. [مخاطبان و کاربردها](#۲-مخاطبان-و-کاربردها)
3. [ساختار محصولات](#۳-ساختار-محصولات)
4. [اعتبار LUM و قیمت‌گذاری](#۴-اعتبار-lum-و-قیمتگذاری)
5. [داشبورد و مسیرها](#۵-داشبورد-و-مسیرها)
6. [ابزارهای تصویر، ویدئو و صدا](#۶-ابزارهای-تصویر-ویدئو-و-صدا)
7. [چت با هوش مصنوعی](#۷-چت-با-هوش-مصنوعی)
8. [Workflow](#۸-workflow)
9. [فایل‌ها، نتایج و گالری](#۹-فایلها-نتایج-و-گالری)
10. [دستیار هوشمند](#۱۰-دستیار-هوشمند)
11. [پلتفرم توسعه‌دهندگان و API](#۱۱-پلتفرم-توسعهدهندگان-و-api)
12. [راهکارهای سازمانی](#۱۲-راهکارهای-سازمانی)
13. [حریم خصوصی، امنیت و محدودیت‌ها](#۱۳-حریم-خصوصی-امنیت-و-محدودیتها)
14. [پرسش‌های متداول](#۱۴-پرسشهای-متداول)
15. [نگهداری و تازگی اطلاعات](#۱۵-نگهداری-و-تازگی-اطلاعات)

## ۱. لوما چیست؟

لوما یک پلتفرم هوش مصنوعی کاربردی متعلق به شرکت «رای بان داده» است. محصول، ابزارهای تولید و پردازش محتوا، مدل‌های زبانی، Workflow، دستیارهای مبتنی بر دانش و API را در اختیار کاربران و کسب‌وکارها قرار می‌دهد.

فعالیت لوما در پاییز ۱۴۰۳ آغاز شد. تمرکز محصول بر دسترسی یکپارچه به ابزارها و مدل‌ها، پرداخت ریالی، تجربهٔ فارسی و ساخت قابلیت‌های کاربردی برای کاربران و کسب‌وکارهای ایرانی است.

**اطلاعات برند و تماس:**

- وب‌سایت: <https://lumai.ir>
- داشبورد: <https://dash.lumai.ir>
- ایمیل: [contact@lumai.ir](mailto:contact@lumai.ir)

## ۲. مخاطبان و کاربردها

| مخاطب | نمونهٔ کاربرد |
| :--- | :--- |
| فروشگاه‌های آنلاین | تصویر محصول، حذف پس‌زمینه، پرو مجازی لباس، و محتوای تبلیغاتی |
| تیم‌های محتوا و آژانس‌ها | تولید و ویرایش تصویر و ویدئو، صداگذاری و آماده‌سازی خروجی کمپین |
| طراحان و تولیدکنندگان محتوا | ایده‌پردازی، ساخت خروجی بصری و استفاده از مدل‌های مختلف |
| کسب‌وکارهای خدماتی | دستیار پاسخ‌گو بر پایهٔ دانش، محتوای وب‌سایت یا اطلاعات محصول |
| توسعه‌دهندگان | اتصال از API یا افزودن دستیار به وب‌سایت و برنامهٔ React |
| تیم‌های دارای فرایند اختصاصی | ساخت Workflow چندمرحله‌ای و ابزارهای متناسب با فرایند |

موارد استفاده شامل ساخت تصویر و ویدئو، ویرایش رسانه، تبدیل گفتار و متن، کار با فایل در Chat، جست‌وجوی دانش و محصول در دستیار وب‌سایت، و خودکارسازی مراحل تکرارشونده با Workflow است. وجود یک نمونهٔ کاربرد در این فهرست، به‌تنهایی تعهد ارائهٔ پروژهٔ اختصاصی نیست.

## ۳. ساختار محصولات

لوما دو تجربهٔ اصلی و یک سطح توسعه‌دهندگان دارد. **Creativity Studio** و **Smart Assistant** از نظر محصول، صورت‌حساب و دسترسی مستقل‌اند؛ خرید یا فعال‌بودن یکی، دسترسی کامل به دیگری ایجاد نمی‌کند.

### Creativity Studio

محیط کاربری برای Chat و ابزارهای تولید یا پردازش تصویر، ویدئو و صدا. Workflow، Assets، Results و Gallery به ساخت، اجرای مجدد، سازمان‌دهی و استفادهٔ دوباره از این خروجی‌ها کمک می‌کنند. مصرف این بخش در وضعیت فعلی عمدتاً براساس LUM و هزینهٔ هر عملیات است.

### Smart Assistant

ابزار ساخت و مدیریت دستیارهای هوشمند با فایل دانش و اطلاعات وب. دستیار می‌تواند در صفحهٔ عمومی، ویجت وب‌سایت یا برنامهٔ متصل‌شده با SDK React ارائه شود. اشتراک و اعتبار پیام آن از کیف پول ابزارهای Creativity Studio جداست.

### Developer Platform

شامل API Key، API عمومی مستندشده، کاتالوگ مدل‌ها، API سازگار با OpenAI Responses و ابزارهای اتصال Smart Assistant است. مسیرهای داخلی داشبورد یا APIهای خصوصی Backend، جزو API عمومی محسوب نمی‌شوند.

## ۴. اعتبار LUM و قیمت‌گذاری

**LUM** واحد اعتبار مصرفی Creativity Studio است. هزینهٔ هر عملیات می‌تواند با مدل، کیفیت، رزولوشن، مدت، ابعاد، تعداد خروجی یا ورودی و تنظیمات دیگر فرق کند. قیمت نشان‌داده‌شده پیش از اجرا یا پرداخت همان عملیات ملاک است.

کد محصول در زمان بازبینی، نرخ پیش‌فرض را **هر ۱ LUM برابر با ۳۴۰ تومان** قرار می‌دهد؛ مقدار قابل استفاده می‌تواند با تنظیم runtime تغییر کند. مالیات و مبلغ نهایی خرید اعتبار در مرحلهٔ پرداخت نمایش داده می‌شود. بنابراین ۳۴۰ تومان را قیمت قطعی و تغییرناپذیر اعلام نکنید.

### مدل فعال Creativity Studio

در وضعیت فعلی، کاربر اعتبار LUM می‌خرد و هزینهٔ ابزارها از آن مصرف می‌شود. طرح اشتراک ماهانهٔ Creativity Studio که در سند مصوب آمده، تا زمان عرضه و امکان خرید در داشبورد، **طرح مصوب/آینده** است و نباید پلن فعال معرفی شود.

جدول قیمت پلن‌های مصوب، با آخرین قیمت‌های ارائه‌شده از سوی مالک محصول:

| پلن مصوب Creativity Studio | پایه | پلاس | پرو | مکس |
| :--- | :---: | :---: | :---: | :---: |
| قیمت ماهانه | ۲۴۹٬۰۰۰ تومان | ۵۹۹٬۰۰۰ تومان | ۱٬۷۹۰٬۰۰۰ تومان | ۴٬۷۴۰٬۰۰۰ تومان |
| LUM ماهانه | ۶۰۰ | ۱٬۶۰۰ | ۵٬۲۰۰ | ۱۵٬۶۰۰ |
| تخفیف خرید LUM اضافی | ۰٪ | ۵٪ | ۱۵٪ | ۲۵٪ |
| فضای ذخیره‌سازی | ۵ گیگابایت | ۲۰ گیگابایت | ۵۰ گیگابایت | ۲۰۰ گیگابایت |
| پردازش هم‌زمان | ۲ | ۴ | ۱۰ | ۲۵ |
| دسترسی زودهنگام به مدل جدید | — | ۷ روز | ۷ روز | ۱۴ روز |
| Preset / Brand Kit | ۳ | ۱۰ | ۳۰ | نامحدود |
| پشتیبانی | استاندارد | استاندارد | اولویت‌دار | اختصاصی |

این ردیف، اطلاعات **پلن مصوب** است، نه قیمت خرید فعال Creativity Studio. پیش از اعلام عمومی، قیمت و عرضه باید با داشبورد و سند سیاست اشتراک تطبیق داده شود.

### اشتراک Smart Assistant

برخلاف اشتراک Creativity Studio، صفحهٔ مدیریت دستیار در محصول فعال است. پلن‌های Free، Plus، Pro و Enterprise، انتخاب مدل و reasoning، سقف اعتبار پیام و محدودیت دانش را کنترل می‌کنند. در نرخ پایهٔ جاری، قیمت محاسباتی Plus برابر ۱٬۷۰۰٬۰۰۰ تومان و Pro برابر ۸٬۵۰۰٬۰۰۰ تومان در ماه است؛ قیمت واقعی از نرخ runtime LUM محاسبه و هنگام خرید نمایش داده می‌شود. Enterprise قیمت قراردادی دارد.

حدود جاری در کد برای پلن‌های استاندارد:

| پلن | اعتبار پیام ماهانه | فایل دانش | سقف مجموع فایل دانش |
| :--- | ---: | ---: | ---: |
| Free | ۵۰ | ۳ فایل | ۳ مگابایت |
| Plus | ۲٬۰۰۰ | ۱۰ فایل | ۱۵ مگابایت |
| Pro | ۱۰٬۰۰۰ | ۵۰ فایل | ۲۵۰ مگابایت |
| Enterprise | براساس تنظیم قرارداد | براساس تنظیم قرارداد | براساس تنظیم قرارداد |

اعتبار پیام مصرف‌شده به مدل و سطح reasoning بستگی دارد؛ تعداد پیام‌ها لزوماً برابر اعتبار پیام نیست. محدودیت‌ها و مبلغ نهایی قابل اعمال به حساب، در رابط اشتراک همان دستیار بررسی شود.

**تفاوت با طرح مصوب:** سند [طرح‌های اشتراکی](Subscription-plan.md) برای Pro مقدار ۳۰٬۰۰۰ اعتبار پیام را به‌عنوان مقدار مصوب/برنامه‌ریزی‌شده ثبت می‌کند؛ پیاده‌سازی جاری محصول ۱۰٬۰۰۰ اعتبار پیام دارد. مقدار زنده را با مقدار مصوب یکی نگیرید.

## ۵. داشبورد و مسیرها

داشبورد اصلی در <https://dash.lumai.ir> قرار دارد. مسیرهای فعلی Next.js که در ناوبری و تجربه‌های داشبورد استفاده می‌شوند شامل این گروه‌ها هستند:

| بخش | مسیرهای اصلی | کاربرد |
| :--- | :--- | :--- |
| نمای اصلی | `/` | خلاصهٔ حساب و دسترسی به بخش‌ها |
| Chat | `/chat` و `/chat/[id]` | گفت‌وگو، مکالمه‌های ذخیره‌شده و فایل‌ها |
| ابزارها | `/service/generate-image`، `/service/edit-image`، `/service/remove-background`، `/service/virtual-try-on`، `/service/upscale-image`، `/service/upscale-video`، `/service/text-to-video`، `/service/image-to-video`، `/service/reference-to-video`، `/service/text-to-speech`، `/service/speech-to-text` | تولید و پردازش رسانه |
| فایل‌ها و خروجی‌ها | `/assets`، `/results`، `/gallery` | مدیریت فایل، نتایج عملیات و محتوای اشتراکی |
| Smart Assistant | `/assistant`، `/assistant/create`، `/assistant/details/[id]` | ساخت، تنظیم و مدیریت دستیار |
| Workflow | `/workflows`، `/workflows/new`، `/workflows/[workflowId]`، `/workflows/[workflowId]/settings` | طراحی و تنظیم Workflow |
| اجرا و اشتراک Workflow | `/workflows/runs`، `/workflows/store`، `/workflows/store/[listingId]`، `/workflows/templates`، `/workflows/templates/[templateId]`، `/workflows/use/[shareId]`، `/workflow-runs/[runId]` | اجراها، قالب‌ها، فروشگاه و صفحات استفاده/اشتراک |
| توسعه‌دهندگان | `/developers/api/keys`، `/developers/api/usage`، `/developers/api/docs` | کلیدها، مصرف API و مستندات |
| مالی | `/billing/packages`، `/billing/transactions`، `/billing/usage` | بسته‌ها، تراکنش‌ها و مصرف |
| حساب و پشتیبانی | `/profile`، `/notifications`، `/support`، `/support/new`، `/support/[publicId]` | پروفایل، اعلان و درخواست پشتیبانی |

داشبورد دارای جست‌وجوی سراسری است. براساس دامنهٔ جست‌وجو، می‌تواند صفحه‌ها و مستندات توسعه‌دهندگان، Workflowهای فروشگاه، فایل‌ها، نتایج و گفتگوها را پیدا کند؛ جست‌وجوی عمیق‌تر برای پیام‌های قدیمی Chat نیز وجود دارد. نتایج به حساب واردشده محدود می‌شوند و محتوای خصوصی حساب نباید در نتایج عمومی ظاهر شود.

نام یا چیدمان منو ممکن است تغییر کند. فهرست بالا routeهای فعلی محصول است، نه تضمین یکسان‌بودن دسترسی هر route برای همهٔ حساب‌ها.

## ۶. ابزارهای تصویر، ویدئو و صدا

همهٔ مسیرهای زیر زیر `/service/` قرار دارند. مدل‌ها، گزینه‌ها و حد ورودی براساس همان سرویس و مدل انتخاب‌شده تعیین می‌شوند؛ پشتیبانی یک مدل از یک قابلیت بیرونی، به معنی در دسترس‌بودن آن گزینه در LUMA نیست.

### تصویر

| ابزار | مسیر | کاری که انجام می‌دهد |
| :--- | :--- | :--- |
| تولید تصویر | `/service/generate-image` | ساخت تصویر از prompt، انتخاب مدل و تنظیمات تصویری |
| ویرایش تصویر | `/service/edit-image` | ویرایش یک یا چند تصویر ورودی براساس دستور |
| حذف پس‌زمینه | `/service/remove-background` | جداسازی سوژه و تولید تصویر با پس‌زمینهٔ شفاف |
| پرو مجازی لباس | `/service/virtual-try-on` | شبیه‌سازی بصری لباس روی تصویر فرد با تنظیمات پوشش و صحنه |
| افزایش کیفیت تصویر | `/service/upscale-image` | بزرگ‌نمایی، حذف نویز، ترمیم یا بازسازی جزئیات براساس مدل |

مدل‌های جاری تصویر و ویرایش شامل خانواده‌های GPT Image 2.5، FLUX 3، Meta Muse Image، MAI Image 2.5، Grok Imagine Image 2، Nano Banana، Recraft V4.1، Seedream 5، Ideogram V4.5، Qwen و مدل‌های دیگر کاتالوگ‌اند. در picker، Sunburst و Flare دو حالت GPT Image 2.5 هستند و کاربر حالت را از انتخاب‌گر همان گروه انتخاب می‌کند. بعضی مدل‌های قدیمی با برچسب `legacy` باقی مانده‌اند؛ آن‌ها را با مدل پیش‌فرض یا انتخاب جاری یکی ندانید.

مدل‌ها ممکن است تصویر شفاف را به‌عنوان ورودی یا خروجی پشتیبانی کنند. حفظ کانال شفافیت به مدل، عملیات و قالب ورودی بستگی دارد؛ هر مدل خروجی شفاف تضمین نمی‌کند. در پرو مجازی، خروجی تصویرسازی است و فیت، اندازه یا جنس واقعی لباس را تضمین نمی‌کند. گزینهٔ حجاب/پوشش در تنظیمات محصول ارائه می‌شود.

### ویدئو

| ابزار | مسیر | ورودی و خروجی |
| :--- | :--- | :--- |
| متن به ویدئو | `/service/text-to-video` | prompt و تنظیمات مدل به ویدئوی تولیدشده تبدیل می‌شوند |
| تصویر به ویدئو | `/service/image-to-video` | تصویر شروع و در مدل‌های پشتیبانی‌شده تصویر پایان به ویدئو تبدیل می‌شوند |
| ویدئوی مرجع‌محور | `/service/reference-to-video` | ترکیب ورودی‌های مرجع تصویری، ویدئویی یا صوتی مطابق مدل |
| افزایش کیفیت ویدئو | `/service/upscale-video` | بهبود وضوح، جزئیات، نویز، تاری یا نرخ فریم براساس مدل |

کاتالوگ ویدئو شامل مدل‌هایی از FLUX 3، MiniMax H3، Grok Imagine Video، Seedance، Gemini Omni، Wan 3.0، Kling 3، LTX 2.5 و Hailuo است. سرویس مرجع‌محور مدل‌های reference-specific دارد. مدل‌های قدیمی ممکن است در فهرست به‌عنوان `legacy` دیده شوند. مدت، نسبت تصویر، رزولوشن، پشتیبانی صدا و تعداد/نوع فایل مرجع برای هر مدل فرق دارد و از تنظیمات فعال همان صفحه خوانده شود.

### گفتار و صدا

#### گفتار به متن

مسیر `/service/speech-to-text` یک فایل صوتی را به متن قابل مرور تبدیل می‌کند. ورودی از بارگذاری فایل، انتخاب فایل موجود در Assets یا ضبط از میکروفون فراهم است؛ کنترل ضبط شامل مکث، ادامه و لغو است. خروجی Scribe v2 می‌تواند متن زمان‌بندی‌شده، قطعه‌بندی واژه‌ها، تشخیص زبان، تفکیک گویندگان، برچسب رویدادهای صوتی و واژه‌های کلیدی برای بهبود تشخیص را دربرگیرد. زبان را می‌توان خودکار تشخیص داد یا در صورت پشتیبانی، راهنمایی کرد. هزینهٔ پایهٔ ثبت‌شده **۱۲ LUM در هر دقیقهٔ صوت** است؛ فعال‌کردن واژه‌های کلیدی ۳۰٪ هزینهٔ بیشتری دارد. مبلغ قبل از اجرا و محدودیت فایل در رابط جاری ملاک است.

#### متن به گفتار

مسیر `/service/text-to-speech` متن را با مدل و صدای انتخابی به فایل صوتی تبدیل می‌کند. کاتالوگ فعلی شامل Gemini 3.1 Flash TTS، Gemini 3.8 Flash و Flash Lite TTS، ElevenLabs Eleven v4 و v4 Turbo، و MiniMax Speech 2.8 Turbo و HD است. Eleven v3 در کاتالوگ با وضعیت legacy دیده می‌شود.

سقف متن و کنترل‌ها به مدل بستگی دارند. بسته به مدل، گزینه‌هایی مانند صدای آماده، سبک بیان، زبان، سرعت، بلندی، زیر و بمی، احساس و قالب خروجی ارائه می‌شوند. صدای انتخابی، تعداد گویندگان، زبان و قیمت را در همان فرم بررسی کنید؛ تنظیمات یک مدل به مدل دیگر تعمیم‌پذیر نیستند. صدای سفارشی یا Voice Cloning را قابلیتی فعال فرض نکنید مگر آنکه در رابط حساب عرضه شده باشد.

## ۷. چت با هوش مصنوعی

مسیر `/chat` یک محیط گفت‌وگو با انتخاب مدل است؛ مکالمه‌ها از مسیر `/chat/[id]` دوباره باز می‌شوند. فهرست مدل‌ها میان ارائه‌دهندگان و خانواده‌های مختلف تغییر می‌کند و انتخاب مدل، reasoning، قابلیت ابزار و هزینه را تحت تأثیر می‌گذارد. برخی مدل‌ها وب‌جست‌وجو یا ابزارهای Chat را پشتیبانی می‌کنند؛ این قابلیت‌ها به مدل و انتخاب task وابسته‌اند.

کاربر می‌تواند فایل‌های متنی و رسانه‌ای پشتیبانی‌شده را در گفتگو استفاده کند. قابلیت‌ها شامل تحلیل PDF و منابع فایل، نمایش مرحله‌های اجرای ابزار، پیش‌نمایش نتیجهٔ در حال تولید، پیگیری درخواست‌های رسانه، تولید و ویرایش artifact در پنل گفتگو، خروجی‌گرفتن از گفتگو و جست‌وجوی مکالمه‌هاست. Chat برای تاریخچهٔ طولانی صفحه‌بندی دارد و جست‌وجوی عمیق داشبورد می‌تواند پاسخ‌های قدیمی را بیابد.

Chat می‌تواند محتوای متنی، کد و جدول را به‌صورت artifact قابل ویرایش نشان دهد. در صورت فعال‌بودن قابلیت تولید فایل Office، ساخت و ویرایش فایل‌های قابل دانلود در قالب‌های **DOCX، XLSX، PPTX و PDF** نیز پشتیبانی می‌شود. کاربر می‌تواند پیشرفت را ببیند، عملیات را لغو کند و در درخواست بعدی برای اصلاح فایل قبلی اقدام کند. نمایش فارسی و راست‌به‌چپ و درج تصویر در تولیدات پشتیبانی‌شده در نظر گرفته شده است؛ نتیجه را قبل از انتشار یا استفادهٔ رسمی بررسی کنید.

هزینهٔ پیام یا مدل ممکن است برآوردی باشد و با مدل، ورودی/خروجی و ابزارهای اجراشده تغییر کند. هزینهٔ نهایی را از سابقه یا صورتحساب محصول بررسی کنید؛ عدد برآوردی تضمین قیمت ثابت نیست.

## ۸. Workflow

Workflow یک Canvas نودمحور برای ساخت و اجرای فرایند چندمرحله‌ای است. کاربر ورودی، نودهای پردازش و خروجی را به هم وصل می‌کند؛ دادهٔ خروجی یک مرحله می‌تواند ورودی مرحلهٔ بعد باشد. قابلیت‌های فعلی شامل اجرای آزمایشی، مشاهدهٔ خروجی میانی، برآورد هزینه، شاخه‌بندی شرطی، پرسیدن سؤال از کاربر و متوقف‌ماندن اجرا تا دریافت پاسخ است.

داشبورد صفحه‌های طراحی، تنظیم، اجرای کاربر، سابقهٔ run، template و store را ارائه می‌کند. اجراهای منتشرشده می‌توانند صفحهٔ استفاده و API داشته باشند. صاحب Workflow می‌تواند runهای منتخب را به‌صورت نمونه یا ورودی Gallery به اشتراک بگذارد؛ اطلاعات نمایش‌داده‌شده از snapshot همان محتوای اشتراکی می‌آید. فایل‌هایی که Workflow به آن‌ها وابسته است برای ادامهٔ کار و run حفظ می‌شوند.

API اجرای Workflow می‌تواند در حالت `waiting` پرسش و گزینه‌های پاسخ را برگرداند و با ثبت پاسخ همان اجرا را ادامه دهد. انواع ورودی و خروجی، فایل‌های مجاز، دسترسی، مبلغ برآوردی و هزینهٔ نهایی به Workflow منتشرشده وابسته‌اند. API Workflow داخلی یا منتشرنشده در دسترس عمومی نیست. برای جزئیات طراحی و استفاده، [راهنمای Workflow](workflow.md) را ببینید.

## ۹. فایل‌ها، نتایج و گالری

سه بخش مرتبط، چرخهٔ عمر رسانه را پوشش می‌دهند:

- **Assets (`/assets`):** فایل‌های بارگذاری‌شده و تولیدشده را جست‌وجو، مرور و باز می‌کند؛ فایل موجود را می‌توان در ابزار سازگار دوباره به‌عنوان ورودی انتخاب کرد.
- **Results (`/results`):** سابقهٔ نتیجه‌ها و درخواست‌های سرویس را نمایش می‌دهد. وضعیت و اطلاعات درخواست به خروجی‌های وابسته کمک می‌کند.
- **Gallery (`/gallery`):** محتوایی را که صاحبان یا کاربران برای نمایش و اشتراک انتخاب کرده‌اند نشان می‌دهد؛ محتوای شخصی صرفاً با تولیدشدن وارد Gallery عمومی نمی‌شود.

جزئیات رسانه می‌تواند منبع یا درخواست مرتبط، پیش‌نمایش، خروجی‌ها و فایل‌های قابل استفادهٔ مجدد را کنار هم قرار دهد. بعضی فایل‌های خروجی Workflow یا Chat نیز در Assets نگهداری می‌شوند. قابلیت حذف، بازیابی و اشتراک به نوع فایل و وضعیت آن بستگی دارد. لینک دانلود خصوصی یا امضاشده را با URL عمومی دائمی اشتباه نگیرید.

## ۱۰. دستیار هوشمند

Smart Assistant ابزاری برای ساخت دستیارهای کسب‌وکار است که از دستورهای مالک، فایل‌های دانش و منابع وب برای پاسخ و راهنمایی استفاده می‌کند. پاسخ‌ها ممکن است ناقص یا نادرست باشند؛ اتصال منبع به معنی پاسخ کاملاً محدود به همان منبع یا تضمین صحت نیست.

### ساخت و مدیریت

مسیرهای اصلی `/assistant`، `/assistant/create` و `/assistant/details/[id]` هستند. صفحهٔ ویرایش، تب‌های نمای کلی، تنظیمات، آزمایش، فایل‌های دانش، استخراج از وب و اشتراک دارد. مالک می‌تواند نام و رفتار دستیار، محتوای راهنما، مدل و سطح reasoning را تنظیم کند و پاسخ را در playground آزمایش کند. سطح اشتراک در مدل‌های قابل انتخاب، reasoning و سقف مصرف اثر می‌گذارد.

### دانش فایل و وب

دستیار می‌تواند از فایل‌های دانش بارگذاری‌شده و اطلاعات استخراج‌شده از وب‌سایت استفاده کند. وضعیت فایل‌ها و استخراج وب در داشبورد قابل پیگیری است؛ تعداد و حجم مجاز براساس پلن اعمال می‌شود. اطلاعات وب می‌تواند با صفحهٔ قابل‌دسترسی و وضعیت استخراج آن مرتبط باشد و الزاماً تغییرات سایت را لحظه‌ای منعکس نمی‌کند.

### مدل و مصرف

مدل پیش‌فرض دستیار جدید **GPT 6 Luna** با سطح reasoning متوسط است. کاتالوگ فعال فعلی شامل GPT 6 Luna، GPT 5.6 Terra، GPT 6 Sol، GPT 6.1 Sol، Gemini 3.8 Flash، Grok 4.7، Claude Sonnet 5.5، DeepSeek V4.1 Flash، GLM 5.3 Flash و Kimi K3 است. مدل‌ها و reasoningهای قابل انتخاب به پلن وابسته‌اند. `NONE` و `MAX` گزینهٔ فعال نیستند؛ سطح‌های پشتیبانی‌نشده هنگام استفاده به سطح مجاز مدل/پلن تبدیل می‌شوند. GPT 5.6 Luna و GPT 5.6 Sol برای دستیارهای قدیمی موجودند، اما برای ساخت یا انتخاب جدید فعال نیستند.

هزینهٔ هر پیام براساس مدل و reasoning از اعتبار پیام اشتراک کم می‌شود. تعداد اعتبار ماهانه در پلن‌های Free، Plus، Pro و Enterprise به‌ترتیب ۵۰، ۲٬۰۰۰، ۱۰٬۰۰۰ و مقدار قراردادی است. قیمت‌های پایه در بخش اشتراک آمده‌اند؛ نرخ runtime و صفحهٔ خرید ملاک نهایی‌اند.

### صفحهٔ عمومی و اتصال وب‌سایت

مالک می‌تواند صفحهٔ عمومی اختصاصی دستیار را فعال یا خاموش کند. وقتی فعال است، بازدیدکننده‌ای که لینک را دارد امکان گفتگو دارد؛ وقتی غیرفعال است، صفحه در دسترس نیست. انتشار عمومی به‌صورت خودکار فعال فرض نشود.

ویجت وب‌سایت از تنظیمات مالک و originهای مجاز استفاده می‌کند. اتصال WordPress با افزونهٔ رسمی ارائه می‌شود. برای سایت React، پکیج فعلی **`@luma-ai/react`** است؛ نام قدیمی `@lumai/react` صحیح نیست. پکیج برای Next.js، TanStack Start/Router، React Router 7/8 و SPA کلاینتی مستند شده است.

در حالت پیشنهادی، API Key روی سرور سایت می‌ماند و سرور، نشست مرورگر را ایجاد می‌کند. حالت بدون کلید فقط برای SPA فاقد Backend است و نیازمند فعال‌سازی صریح و افزودن origin مجاز در تنظیمات دستیار است. کلید را در کد مرورگر یا متغیر عمومی قرار ندهید.

### دادهٔ زنده، راهبری و اقدام در سایت

در اتصال `@luma-ai/react`، توسعه‌دهنده می‌تواند context و منبع دادهٔ سایت، جست‌وجوی صفحه یا محصول، واکشی جزئیات محصول، navigation و actionهای تعریف‌شده برای همان سایت را فراهم کند. سایت‌هایی که data source سازگار دارند می‌توانند اطلاعات صفحه/محصول را هنگام گفتگو به دستیار بدهند. افزونهٔ WordPress نیز منو و صفحه‌های عمومی و در صورت نصب WooCommerce، محصولات ساده و متغیر را برای جست‌وجوی عمومی عرضه می‌کند.

دستیار می‌تواند visitor را در صفحه راهنمایی کند، راهنمای چندمرحله‌ای را با تعامل‌های واقعی صفحه پیش ببرد و مقصد هم‌دامنه‌ای را برای navigation پیشنهاد دهد. visitor، پیش از navigation یا اجرای action تعریف‌شده، آن را تأیید می‌کند و می‌تواند راهنما را لغو کند. مدل نمی‌تواند به‌جای visitor فرم را ارسال کند، خرید انجام دهد یا دادهٔ حساس وارد کند. قابلیت‌ها به adapter، داده‌ها و کنترل‌های ایمنی وب‌سایت میزبان وابسته‌اند؛ پشتیبانی همگانی از همهٔ قالب‌ها، iframeها یا برنامه‌های وب ادعا نمی‌شود.

مستندات توسعه‌دهنده در <https://dash.lumai.ir/docs/react> و راهنمای عامل‌های کدنویس در <https://dash.lumai.ir/llms.txt> و <https://dash.lumai.ir/llms-full.txt> در دسترس‌اند.

## ۱۱. پلتفرم توسعه‌دهندگان و API

API محصول از سرور LUMA و با API Key استفاده می‌شود. کلید محرمانه است و باید فقط در محیط سرور یا secret manager قرار بگیرد؛ آن را در مرورگر، مخزن عمومی یا log منتشر نکنید. آدرس پایهٔ مسیرهای v1 در حال حاضر <https://dash.lumai.ir/api/v1> است. سطح دسترسی و موجودی حساب بر درخواست‌ها اثر می‌گذارد.

### Responses API سازگار با OpenAI

`POST /responses` یک Responses API **سازگار با OpenAI** ارائه می‌دهد؛ درخواست غیرجریانی و streaming با رویدادهای SSE در دسترس‌اند. پیاده‌سازی از function tools، خروجی JSON Schema و تنظیمات reasoning پشتیبانی می‌کند، اما امکانات به مدل انتخابی وابسته‌اند. این به معنی سازگاری کامل با همهٔ قابلیت‌ها یا رفتارهای OpenAI نیست؛ پاسخ‌های ذخیره‌شده، اجرای background و ابزارهای میزبانی‌شدهٔ OpenAI در این endpoint ارائه نمی‌شوند.

### مسیرهای عمومی API v1

در نسخهٔ جاری، APIهای مستندشده و ثبت‌شده شامل موارد زیرند. مسیرها نسبت به `/api/v1` هستند و API Key می‌خواهند، مگر آنکه خلافش ذکر شود:

| روش و مسیر | کاربرد |
| :--- | :--- |
| `GET /me` | اطلاعات حساب صاحب کلید، اعتبار قابل استفاده، پلن‌های فعال و زمان آخرین استفاده |
| `GET /models` و `GET /models/:model` | فهرست مدل‌های Responses، قابلیت‌ها، قیمت توکنی و دسترسی مدل برای حساب |
| `POST /responses` | تولید پاسخ متنی یا جریانی با قرارداد Responses سازگار با OpenAI |
| `GET /media/models` | مدل‌های رسانه، schema پارامترها و وضعیت دسترسی؛ پارامتر `service` اختیاری است |
| `POST /audio/speech-to-text` و `POST /audio/text-to-speech` | ثبت درخواست تبدیل گفتار و متن؛ پردازش غیرهم‌زمان |
| `POST /images/generate`، `/images/edit`، `/images/upscale`، `/images/remove-background`، `/images/virtual-try-on` | ثبت درخواست ابزارهای تصویر |
| `POST /videos/text-to-video`، `/videos/image-to-video`، `/videos/upscale`، `/videos/reference-to-video` | ثبت درخواست ابزارهای ویدئو |
| `GET /requests/:id` | خواندن وضعیت و خروجی درخواست رسانهٔ متعلق به حساب |
| `GET /assets/:id/media` و `GET /assets/:id/media/:variant` | دریافت فایل یا variant متعلق به حساب، با redirect موقت |
| `GET /workflows/:shareId`، `POST /workflows/:shareId/runs` | خواندن Workflow منتشرشده و ثبت اجرا |
| `GET /workflow-runs/:id`، `POST /workflow-runs/:id/answer` | خواندن وضعیت اجرای متعلق به حساب و پاسخ به پرسش آن |

درخواست‌های رسانه می‌توانند `202 Accepted` برگردانند؛ کلاینت وضعیت را با `GET /requests/:id` یا مسیر run مربوط دنبال می‌کند. ورودی‌های فایل API رسانه URL می‌پذیرند و برای فیلدهای مستندشده، multipart نیز پشتیبانی می‌شود. سند `GET /api/v1/openapi.json` عمومی است و برای دریافت schema به API Key نیاز ندارد.

`GET /api/catalog/models` یک endpoint جداگانه و عمومی برای کاتالوگ مدل‌های سایت است؛ authentication نمی‌خواهد و اطلاعات عمومی سرویس‌های رسانه و Chat را با برچسب قابلیت و قیمت شروع/نرخ مدل برمی‌گرداند. این endpoint با `GET /api/v1/models` یکی نیست: دومی مدل‌های Responses را برای حساب API و با احراز هویت فهرست می‌کند.

API داشبورد، API عمومی مستندشده و مسیرهای داخلی سرور یکسان نیستند. endpointهای session-based داخلی، admin یا مسیرهای خصوصی را API عمومی معرفی نکنید.

## ۱۲. راهکارهای سازمانی

برای نیازهای فراتر از ابزارهای آماده، دامنهٔ همکاری می‌تواند شامل طراحی دستیار دانش، اتصال API به فرایند کسب‌وکار، Workflow اختصاصی یا پروژهٔ پردازش محتوا باشد. این موارد پیشنهادهای قابل بررسی‌اند، نه لزوماً سرویس آماده یا تعهد عمومی.

فرایند همکاری معمولاً شامل نیازسنجی، تعریف دامنه، برآورد، توسعه و آزمایش و سپس توافق استقرار و پشتیبانی است. قیمت، زمان، SLA و مسئولیت داده باید در پیشنهاد یا قرارداد مشخص شوند.

## ۱۳. حریم خصوصی، امنیت و محدودیت‌ها

- خروجی مدل ممکن است نادرست، ناقص یا مشابه خروجی دیگران باشد؛ آن را قبل از استفادهٔ مهم یا تجاری بازبینی کنید.
- API Key و اطلاعات ورود محرمانه‌اند؛ در اختیار کاربر یا سرویس غیرمجاز نگذارید.
- در دستیار وب‌سایت، فقط داده‌ای را به منبع دستیار متصل کنید که مجاز به ارائه به بازدیدکننده هستید.
- اطلاعات صفحه و محصولات سایت باید با دسترسی عمومی و تنظیمات حذف/محدودسازی همان سایت تطبیق داده شوند.
- وجود کنترل‌های فنی به معنی امنیت مطلق، گواهی رسمی یا انطباق حقوقی خاص نیست؛ چنین ادعایی فقط با مدرک معتبر مجاز است.
- جزئیات جمع‌آوری، نگهداری، حذف داده، حقوق خروجی و تعهدهای کاربر در اسناد حقوقی جاری توضیح داده می‌شوند:
  - [شرایط استفاده، حقوق و تعهدات کاربران](https://luma-knowledge.pages.dev/k/terms-of-use.md)
  - [سیاست‌ها، حریم خصوصی و حقوق کاربران](https://luma-knowledge.pages.dev/k/terms-policies.md)

## ۱۴. پرسش‌های متداول

### آیا استفاده از ابزارهای آماده به دانش فنی نیاز دارد؟

معمولاً خیر. Workflow پیشرفته و API به شناخت بیشتر از ورودی، خروجی و منطق فرایند نیاز دارند.

### آیا Creativity Studio اشتراک ماهانه دارد؟

مدل فعال فعلی براساس خرید و مصرف LUM است. قیمت جدول پلن‌های پایه تا مکس در این سند، قیمت طرح مصوب است؛ تا زمانی که در داشبورد قابل خرید نشده، پلن جاری معرفی نمی‌شود.

### آیا دستیار هوشمند فقط از فایل‌های دانش پاسخ می‌دهد؟

خیر؛ فایل و منبع وب زمینهٔ پاسخ را فراهم می‌کنند، اما صحت کامل یا محدودماندن قطعی پاسخ به منابع تضمین نمی‌شود. رفتار به تنظیمات و منابع دستیار وابسته است.

### آیا می‌توان فایل Word، Excel، PowerPoint یا PDF ساخت؟

Chat در صورت فعال‌بودن قابلیت فایل Office، خروجی DOCX، XLSX، PPTX و PDF می‌سازد و می‌تواند برای اصلاح فایل کمک کند. دسترسی را در همان گفتگو بررسی کنید.

### آیا دستیار می‌تواند در وب‌سایت navigation یا action انجام دهد؟

در اتصال سازگار، می‌تواند مقصد یا action تعریف‌شده را پیشنهاد کند؛ navigation یا اجرای action نیازمند تأیید visitor است. این قابلیت جایگزین ورود، تکمیل فرم حساس یا خرید توسط کاربر نیست.

### آیا مدل‌ها و هزینه‌ها ثابت‌اند؟

خیر. فهرست، legacy status، دسترسی پلن و قیمت مدل ممکن است تغییر کند. داشبورد، API یا مبلغ مرحلهٔ پرداخت برای درخواست جاری را ملاک بگیرید.

### آیا خرید یک محصول به بقیهٔ محصولات دسترسی می‌دهد؟

نه لزوماً. Creativity Studio، Workflow و Smart Assistant محدودیت دسترسی و مصرف جداگانه دارند؛ جزئیات مؤثر را هنگام خرید یا اجرا بررسی کنید.

## ۱۵. نگهداری و تازگی اطلاعات

این سند در صورت تغییر مسیرها، ابزارها، مدل‌ها، API، اشتراک، قیمت‌گذاری، Workflow، Smart Assistant یا سیاست‌های حقوقی باید بازبینی شود. در هر بازبینی:

1. پیاده‌سازی و رابط جاری بررسی شوند؛
2. وضعیت فعال از طرح مصوب و برنامهٔ آینده جدا بماند؛
3. قیمت و محدودیت از منبع مرجع مربوط استخراج شود؛
4. مسیر API عمومی از endpoint داخلی و خصوصی تفکیک شود؛
5. مغایرت با FAQ، راهنمای Workflow و قیمت‌گذاری ثبت شود و بدون تأیید، اسناد دیگر بازنویسی نشوند.

---

**تاریخ بازبینی محصول:** ۱۵ مهر ۱۴۰۵ (۷ اکتبر ۲۰۲۶)

**نسخهٔ مرجع:** ۱.۴