مستندات فنی

API عمومیِ رؤیا

با REST API رؤیا می‌توانی مستقیماً از کدِ خودت، تولیدِ تصویر، ویدیو، صدا و کاراکترهای اختصاصی را صدا بزنی — دقیقاً همان موتوری که استودیوی رؤیا هم از آن استفاده می‌کند.

آدرسِ پایه: https://roya.hashpa.com/api/v1

ساختِ کلید اتصالِ MCP

اولین درخواست در ۶۰ ثانیه

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

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

curl -X POST https://roya.hashpa.com/api/v1/images \
  -H "Authorization: Bearer roya_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "flux-pro", "prompt": "یک گربه‌ی نارنجی روی مبل" }'

احراز هویت

هر درخواست باید هدرِ زیر را داشته باشد؛ کلید را از صفحه‌ی کلیدهای API بساز:

Authorization: Bearer roya_sk_xxxxxxxx

هر درخواست از اعتبار (کردیت)ِ صاحبِ همان کلید کسر می‌شود — دقیقاً از همان مسیرِ پول‌شمارِ استودیو.

کدهایِ وضعیتِ پاسخ
کد	معنی
200 / 202	موفق — 200 برای نقاطِ همزمان (نتیجه در همان پاسخ)، 202 برای نقاطِ ناهمزمان (کار صف شد).
401	کلیدِ نامعتبر یا باطل‌شده.
402	اعتبارِ ناکافی — همراه با `needed` و `balance` در بدنه‌ی پاسخ.
429	عبور از سقفِ نرخِ درخواست.

سقفِ نرخ و نسخه‌بندی

هر کلید در هر دقیقه حداکثر ۶۰ درخواست دارد (پیش‌فرض)؛ هر پاسخ هدرهایِ X-RateLimit-Limit، X-RateLimit-Remaining و X-RateLimit-Reset را برمی‌گرداند. عبورِ سقف → 429؛ بر اساسِ X-RateLimit-Reset دوباره امتحان کن.
همه‌ی مسیرها زیرِ پیشوندِ نسخه‌دارِ /api/v1 هستند — این پیشوند را در کدت pin کن؛ نسخه‌ی فعلی پایدار می‌ماند.

اتصالِ MCP

رؤیا را به‌عنوانِ یک ابزار به دستیارِ هوش‌مصنوعیت (Claude Code، Cursor، Claude Desktop) وصل کن. توکنِ اتصال را از صفحه‌ی اتصال‌ها بساز.

آدرسِ سرور: https://roya.hashpa.com/api/mcp — transport: HTTP، احرازِ هویت: Authorization: Bearer <توکن>

Claude Code (CLI)

claude mcp add --transport http roya https://roya.hashpa.com/api/mcp \
  --header "Authorization: Bearer roya_mcp_xxxxxxxx"

Cursor

{
  "mcpServers": {
    "roya": {
      "url": "https://roya.hashpa.com/api/mcp",
      "headers": {
        "Authorization": "Bearer roya_mcp_xxxxxxxx"
      }
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "roya": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://roya.hashpa.com/api/mcp",
        "--header",
        "Authorization: Bearer roya_mcp_xxxxxxxx"
      ]
    }
  }
}

تصویر

POST/api/v1/images

تولید تصویر (متن‌به‌تصویر)

همزمان

از رویِ یک پرامپتِ متنی تصویر می‌سازد. همزمان (sync) اجرا می‌شود و در همان پاسخ، آدرسِ تصویرهای ساخته‌شده برمی‌گردد.

فیلدهایِ بدنه (JSON)
فیلد	نوع	الزامی؟	توضیح
model_id	string	شرطی	آی‌دیِ مدل — یکی از model_id یا slug الزامی است
slug	string	شرطی	اسلاگِ مدل — یکی از model_id یا slug الزامی است
prompt	string	بله	متنِ توصیفِ تصویر
n	number	خیر	تعدادِ تصویرِ خروجی (پیش‌فرض ۱؛ سقف بسته به مدل)
aspect_ratio	string	خیر	نسبتِ تصویر (مثلاً "1:1"، "16:9")؛ باید در فهرستِ پشتیبانی‌شده‌ی مدل باشد
resolution_tier	string	خیر	سطحِ کیفیت/رزولوشن؛ باید در فهرستِ پشتیبانی‌شده‌ی مدل باشد
preset_id	string	خیر	آی‌دیِ یک پریستِ سبک؛ پیش از قیمت‌گذاری به پرامپت افزوده می‌شود
lora_ids	string[]	خیر	آی‌دیِ کاراکترهای LoRA‌ی خودت (از /characters/train) برای تولیدِ تصویرِ همان کاراکتر
image_urls	string[]	خیر	آدرسِ تصویرهای مرجع (http/https عمومی) برای مدل‌های ادیت‌پذیر

نمونه‌ی درخواست

curl -X POST https://roya.hashpa.com/api/v1/images \
  -H "Authorization: Bearer roya_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "flux-pro",
    "prompt": "یک گربه‌ی نارنجی روی مبل، نورِ نرمِ عصرگاهی",
    "n": 1,
    "aspect_ratio": "1:1"
  }'

پاسخ

// 200
{
  "id": "gen_...",
  "urls": ["https://.../image/....png"],
  "credits_charged": 12,
  "credits_balance": 488
}

همزمان (sync) است؛ نیازی به polling نیست.

POST/api/v1/edit-image

ویرایش تصویر

همزمان

تصویرِ موجود را بر اساسِ یک دستورِ متنی ویرایش می‌کند (inpaint/edit). فقط برای مدل‌هایی که ورودیِ تصویر می‌خواهند.

فیلدهایِ بدنه (JSON)
فیلد	نوع	الزامی؟	توضیح
model_id	string	شرطی	یکی از model_id یا slug الزامی است
slug	string	شرطی	یکی از model_id یا slug الزامی است
prompt	string	بله	دستورِ ویرایش
image_url	string	بله	آدرسِ عمومیِ (http/https) تصویرِ مبدأ
mask_url	string	شرطی	آدرسِ ماسک؛ فقط برای مدل‌هایی که ماسک لازم دارند
reference_image_url	string	شرطی	آدرسِ تصویرِ مرجعِ اضافه؛ فقط برای مدل‌هایی که آن را لازم دارند
n	number	خیر	تعدادِ خروجی (پیش‌فرض ۱)
resolution	string	خیر	رزولوشنِ خروجی، اگر مدل بپذیرد

نمونه‌ی درخواست

curl -X POST https://roya.hashpa.com/api/v1/edit-image \
  -H "Authorization: Bearer roya_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "flux-fill",
    "prompt": "پس‌زمینه را به یک ساحلِ آفتابی تغییر بده",
    "image_url": "https://example.com/photo.jpg"
  }'

پاسخ

// 200
{
  "id": "gen_...",
  "urls": ["https://.../image/....png"],
  "credits_charged": 14,
  "credits_balance": 474
}

همزمان (sync) است؛ نیازی به polling نیست.

ویدیو

POST/api/v1/videos

تولید ویدیو

ناهمزمان

از رویِ متن (یا متن + تصویرِ فریمِ اول/آخر) ویدیو می‌سازد. ناهمزمان (async) است — پاسخ بلافاصله برمی‌گردد و باید با /api/v1/generations/{id} پیگیری شود.

فیلدهایِ بدنه (JSON)
فیلد	نوع	الزامی؟	توضیح
model_id	string	شرطی	یکی از model_id یا slug الزامی است
slug	string	شرطی	یکی از model_id یا slug الزامی است
prompt	string	بله	متنِ توصیفِ ویدیو
duration	number	خیر	مدتِ ویدیو به ثانیه؛ باید در فهرستِ پشتیبانی‌شده‌ی مدل باشد
resolution	string	خیر	رزولوشن (پیش‌فرض "720p" اگر مدل پشتیبانی کند)
aspect_ratio	string	خیر	نسبتِ تصویر (پیش‌فرض "16:9" اگر مدل پشتیبانی کند)
audio	boolean	خیر	درخواستِ صدا همراهِ ویدیو؛ فقط برای مدل‌هایی که این قابلیت را دارند
image_url	string	خیر	آدرسِ تصویرِ فریمِ اول برای حالتِ تصویر‌به‌ویدیو
last_frame_url	string	شرطی	آدرسِ تصویرِ فریمِ آخر؛ فقط همراه با image_url معنا دارد
preset_id	string	خیر	آی‌دیِ یک پریستِ سبک؛ به پرامپت افزوده می‌شود

نمونه‌ی درخواست

curl -X POST https://roya.hashpa.com/api/v1/videos \
  -H "Authorization: Bearer roya_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "kling-2.6",
    "prompt": "موجِ آرامِ دریا هنگامِ غروب",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

پاسخ

// 202
{
  "id": "gen_...",
  "status": "queued",
  "credits_charged": 60,
  "credits_balance": 428
}

ناهمزمان (async) است — نتیجه را از /api/v1/generations/{id} بگیر.

POST/api/v1/edit-video

ویرایش ویدیو

ناهمزمان

ویدیوی موجود را بر اساسِ یک دستورِ متنی ویرایش/بازتولید یا تمدید می‌کند. ناهمزمان (async) است.

فیلدهایِ بدنه (JSON)
فیلد	نوع	الزامی؟	توضیح
model_id	string	شرطی	یکی از model_id یا slug الزامی است
slug	string	شرطی	یکی از model_id یا slug الزامی است
video_url	string	بله	آدرسِ عمومیِ ویدیوی مبدأ
prompt	string	شرطی	دستورِ ویرایش؛ برای بعضی مدل‌های تمدیدِ ویدیو اختیاری است
duration	number	خیر	فقط برای مدل‌هایِ «تمدیدِ ویدیو»: تعدادِ ثانیه‌ی اضافه‌شونده
mode	string	خیر	فقط برای مدل‌هایِ «تمدیدِ ویدیو»: "start" یا "end" — کدام سرِ ویدیو تمدید شود
resolution	string	خیر	رزولوشنِ خروجی، اگر مدل بپذیرد
image_urls	string[]	خیر	آدرسِ تصویرهای مرجعِ اضافه؛ فقط در بعضی مدل‌ها
keep_audio	boolean	خیر	نگه‌داشتنِ صدایِ اصلیِ ویدیو؛ فقط در بعضی مدل‌ها

نمونه‌ی درخواست

curl -X POST https://roya.hashpa.com/api/v1/edit-video \
  -H "Authorization: Bearer roya_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "kling-video-edit",
    "video_url": "https://example.com/clip.mp4",
    "prompt": "رنگِ صحنه را گرم‌تر و پاییزی کن"
  }'

پاسخ

// 202
{
  "id": "gen_...",
  "status": "queued",
  "credits_charged": 45,
  "credits_balance": 383
}

ناهمزمان (async) است — نتیجه را از /api/v1/generations/{id} بگیر. مدتِ ویدیوی ورودی برای بیشترِ مدل‌ها سمتِ سرور اندازه‌گیری می‌شود، نه از رویِ ادعایِ کلاینت.

POST/api/v1/motion

کنترلِ حرکت (Motion Control)

ناهمزمان

حرکتِ یک ویدیوی مرجع را به تصویرِ یک کاراکتر/سوژه منتقل می‌کند. ناهمزمان (async) است.

فیلدهایِ بدنه (JSON)
فیلد	نوع	الزامی؟	توضیح
model_id	string	شرطی	یکی از model_id یا slug
slug	string	شرطی	یکی از model_id یا slug
image_url	string	بله	آدرسِ تصویرِ کاراکتر/سوژه‌ای که باید حرکت کند
video_url	string	بله	آدرسِ ویدیوی مرجعِ حرکت
prompt	string	خیر	توضیحِ اختیاریِ صحنه/حرکت
character_orientation	string	شرطی	"image" یا "video" — مرجعِ جهت‌گیریِ کاراکتر؛ برای بعضی مدل‌ها الزامی است
resolution	string	خیر	رزولوشنِ خروجی؛ فقط در بعضی مدل‌ها

نمونه‌ی درخواست

curl -X POST https://roya.hashpa.com/api/v1/motion \
  -H "Authorization: Bearer roya_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "kling-motion-control",
    "image_url": "https://example.com/character.jpg",
    "video_url": "https://example.com/reference-motion.mp4",
    "character_orientation": "image"
  }'

پاسخ

// 202
{
  "id": "gen_...",
  "status": "queued",
  "credits_charged": 70,
  "credits_balance": 313
}

ناهمزمان (async) است — نتیجه را از /api/v1/generations/{id} بگیر. مدتِ ویدیوی مرجع سمتِ سرور اندازه‌گیری می‌شود.

POST/api/v1/lipsync

لب‌سینک (Lipsync)

ناهمزمان

ویدیو یا تصویرِ یک چهره را با صدا یا متن هماهنگ می‌کند (حرکتِ لب منطبق بر گفتار). ناهمزمان (async) است.

فیلدهایِ بدنه (JSON)
فیلد	نوع	الزامی؟	توضیح
model_id	string	شرطی	یکی از model_id یا slug
slug	string	شرطی	یکی از model_id یا slug
video_url	string	شرطی	آدرسِ ویدیوی هدف (حالتِ ویدیو+صدا)
image_url	string	شرطی	آدرسِ تصویرِ چهره (حالتِ تصویر+صدا/آواتار)
audio_url	string	شرطی	آدرسِ فایلِ صوتیِ گفتار
text	string	شرطی	متنی که با TTS به گفتار تبدیل و لب‌سینک می‌شود (به‌جایِ audio_url)
voice_id	string	خیر	آی‌دیِ صدا؛ فقط در حالتِ متن‌محور
voice_language	string	خیر	زبانِ گفتار؛ فقط در حالتِ متن‌محور
voice_speed	number	خیر	سرعتِ گفتار؛ فقط در حالتِ متن‌محور
sync_mode	string	خیر	راهبردِ هماهنگ‌سازی، بسته به مدل
model	string	خیر	فقط برای واریانتِ sync-lipsync نسخهٔ ۲ — یکی از lipsync-2 یا lipsync-2-pro
prompt	string	خیر	راهنماییِ اضافه، بسته به مدل

نمونه‌ی درخواست

curl -X POST https://roya.hashpa.com/api/v1/lipsync \
  -H "Authorization: Bearer roya_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "omnihuman",
    "image_url": "https://example.com/avatar.jpg",
    "audio_url": "https://example.com/speech.mp3"
  }'

پاسخ

// 202
{
  "id": "gen_...",
  "status": "queued",
  "credits_charged": 55,
  "credits_balance": 258
}

ناهمزمان (async) است — نتیجه را از /api/v1/generations/{id} بگیر. ترکیبِ دقیقِ فیلدهای لازم (ویدیو+صدا یا تصویر+صدا/متن) به مدلِ انتخابی بستگی دارد.

صدا

POST/api/v1/audio

تبدیلِ متن به گفتار (TTS)

ناهمزمان

متن را به فایلِ صوتیِ گفتار تبدیل می‌کند. ناهمزمان (async) است.

فیلدهایِ بدنه (JSON)
فیلد	نوع	الزامی؟	توضیح
model_id	string	شرطی	یکی از model_id یا slug
slug	string	شرطی	یکی از model_id یا slug
text	string	بله	متنِ گفتار (حداکثر ۶۰۰ کاراکتر)
voice	string	خیر	آی‌دی/نامِ صدا
format	string	خیر	فرمتِ خروجی، بسته به مدل
speed	number	خیر	سرعتِ گفتار
emotion	string	خیر	حس/سبکِ بیان
language	string	خیر	کدِ زبان

نمونه‌ی درخواست

curl -X POST https://roya.hashpa.com/api/v1/audio \
  -H "Authorization: Bearer roya_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "elevenlabs-tts",
    "text": "سلام، به رؤیا خوش اومدی!",
    "voice": "fa-warm-1"
  }'

پاسخ

// 202
{
  "id": "gen_...",
  "status": "queued",
  "credits_charged": 8,
  "credits_balance": 250
}

ناهمزمان (async) است — نتیجه را از /api/v1/generations/{id} بگیر.

POST/api/v1/music

تولید موسیقی/افکتِ صوتی

ناهمزمان

بسته به مدلِ انتخابی، موسیقی یا افکتِ صوتی می‌سازد. ناهمزمان (async) است.

فیلدهایِ بدنه (JSON)
فیلد	نوع	الزامی؟	توضیح
model_id	string	شرطی	یکی از model_id یا slug
slug	string	شرطی	یکی از model_id یا slug
prompt	string	شرطی	توضیحِ موسیقی/افکت (معادلِ text)
text	string	شرطی	معادلِ prompt — یکی از این دو الزامی است
lyrics	string	خیر	متنِ ترانه؛ فقط در حالتِ موسیقی
is_instrumental	boolean	خیر	بدونِ آواز (بی‌کلام)؛ فقط در حالتِ موسیقی
lyrics_optimizer	boolean	خیر	بهبودِ خودکارِ متنِ ترانه؛ فقط در حالتِ موسیقی
audio_setting	object	خیر	تنظیماتِ کدکِ خروجی: { sample_rate?, format?, bitrate? }؛ فقط در حالتِ موسیقی
negative_prompt	string	خیر	آنچه باید نادیده گرفته شود؛ فقط در حالتِ موسیقی
seed	number	خیر	بذرِ تصادفی برایِ تکرارپذیری
duration_seconds	number	خیر	مدتِ افکتِ صوتی؛ فقط در حالتِ افکت (SFX)
prompt_influence	number	خیر	میزانِ پیرویِ افکت از پرامپت؛ فقط در حالتِ SFX
output_format	string	خیر	فرمتِ خروجی؛ فقط در حالتِ SFX
loop	boolean	خیر	حلقه‌ای‌بودنِ افکت؛ فقط در حالتِ SFX

نمونه‌ی درخواست

curl -X POST https://roya.hashpa.com/api/v1/music \
  -H "Authorization: Bearer roya_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "minimax-music",
    "prompt": "یک آهنگِ پاپِ شاد با ریتمِ تند",
    "is_instrumental": false
  }'

پاسخ

// 202
{
  "id": "gen_...",
  "status": "queued",
  "credits_charged": 30,
  "credits_balance": 220
}

حالتِ موسیقی/افکت خودکار از رویِ مدلِ انتخابی تشخیص داده می‌شود — فیلدی برایِ انتخابِ حالت وجود ندارد. ناهمزمان است — نتیجه را از /api/v1/generations/{id} بگیر.

POST/api/v1/transcribe

رونویسیِ صدا به متن

ناهمزمان

فایلِ صوتی را به متن تبدیل می‌کند. ناهمزمان (async) است؛ با poll‌کردنِ generation، فیلدِ output_urls[0] یک آدرسِ فایلِ متنی (.txt) است — آن را fetch کن تا متنِ رونویسی را بگیری (نه متنِ inline).

فیلدهایِ بدنه (JSON)
فیلد	نوع	الزامی؟	توضیح
model_id	string	شرطی	یکی از model_id یا slug
slug	string	شرطی	یکی از model_id یا slug
audio_url	string	بله	آدرسِ عمومیِ فایلِ صوتی (حداکثر ۶۰۰ ثانیه)
language	string	خیر	زبانِ گفتار (کمک به دقتِ رونویسی)

نمونه‌ی درخواست

curl -X POST https://roya.hashpa.com/api/v1/transcribe \
  -H "Authorization: Bearer roya_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "whisper-large",
    "audio_url": "https://example.com/voice-note.mp3",
    "language": "fa"
  }'

پاسخ

// 202
{
  "id": "gen_...",
  "status": "queued",
  "credits_charged": 5,
  "credits_balance": 215
}

پاسخِ این درخواست فقط تأییدِ صف‌شدنِ کار است؛ متنِ نهایی را از /api/v1/generations/{id} (فیلدِ output_urls) بگیر.

POST/api/v1/voice

تبدیل/کلونِ صدا

ناهمزمان

صدای یک فایل را تغییر می‌دهد یا با صدایِ مرجعِ دیگری جایگزین می‌کند. ناهمزمان (async) است.

فیلدهایِ بدنه (JSON)
فیلد	نوع	الزامی؟	توضیح
model_id	string	شرطی	یکی از model_id یا slug
slug	string	شرطی	یکی از model_id یا slug
audio_url	string	شرطی	آدرسِ عمومیِ فایلِ صوتیِ ورودی
source_audio_url	string	شرطی	آدرسِ صدای مبدأ؛ در حالتِ تبدیلِ صدا
target_voice_audio_url	string	شرطی	آدرسِ صدایِ هدف (مرجع)؛ در حالتِ کلونِ صدا
voice	string	خیر	آی‌دیِ یک صدایِ آماده
text	string	خیر	متن؛ در جریان‌هایِ کلون‌صدا+گفتار
model	string	خیر	انتخاب‌گرِ داخلیِ مدلِ ارائه‌دهنده (جدا از model_id)
noise_reduction	boolean	خیر	کاهشِ نویز
need_volume_normalization	boolean	خیر	نرمال‌سازیِ بلندیِ صدا
accuracy	number	خیر	میزانِ دقت/شدتِ تبدیل
remove_background_noise	boolean	خیر	حذفِ نویزِ پس‌زمینه
seed	number	خیر	بذرِ تصادفی
output_format	string	خیر	فرمتِ خروجی

نمونه‌ی درخواست

curl -X POST https://roya.hashpa.com/api/v1/voice \
  -H "Authorization: Bearer roya_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "voice-clone",
    "source_audio_url": "https://example.com/my-voice.mp3",
    "target_voice_audio_url": "https://example.com/target-voice.mp3"
  }'

پاسخ

// 202
{
  "id": "gen_...",
  "status": "queued",
  "credits_charged": 20,
  "credits_balance": 195
}

کدام‌یک از فیلدهای *_url الزامی است به مدلِ انتخابی (تبدیلِ صدا یا کلونِ صدا) بستگی دارد. ناهمزمان است — نتیجه را از /api/v1/generations/{id} بگیر.

اپ‌ها

POST/api/v1/apps

اجرایِ یک اپ (حذفِ پس‌زمینه، آپ‌اسکیل، فیس‌سواپ و…)

ناهمزمان

اپ‌های آماده (مثلِ حذفِ پس‌زمینه، پاک‌کن، تعویضِ چهره، آپ‌اسکیل، ری‌لایت) را اجرا می‌کند. ناهمزمان (async) است.

فیلدهایِ بدنه (JSON)
فیلد	نوع	الزامی؟	توضیح
model_id	string	شرطی	یکی از model_id یا slug
slug	string	شرطی	یکی از model_id یا slug
params	object	خیر	پارامترهایِ اختصاصیِ همان اپ (مثلاً image_url)؛ پیش‌فرض شیءِ خالی. فیلدهایِ رسانه باید آدرسِ عمومیِ http(s) باشند، نه data URL

نمونه‌ی درخواست

curl -X POST https://roya.hashpa.com/api/v1/apps \
  -H "Authorization: Bearer roya_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "bg-remove",
    "params": { "image_url": "https://example.com/photo.jpg" }
  }'

پاسخ

// 202
{
  "id": "gen_...",
  "status": "queued",
  "credits_charged": 6,
  "credits_balance": 189
}

شکلِ دقیقِ params به schema همان اپ بستگی دارد — از /api/v1/models برای دیدنِ فهرستِ اپ‌های فعال کمک بگیر. ناهمزمان است — نتیجه را از /api/v1/generations/{id} بگیر.

کاراکتر

POST/api/v1/characters/train

آموزشِ کاراکترِ اختصاصی (LoRA)

ناهمزمان

از رویِ چند عکسِ مرجع، یک کاراکترِ اختصاصی (LoRA) آموزش می‌دهد که بعداً در /api/v1/images با lora_ids قابلِ استفاده است.

فیلدهایِ بدنه (JSON)
فیلد	نوع	الزامی؟	توضیح
images_zip_url	string	بله	آدرسِ عمومیِ یک فایلِ zip از عکس‌هایِ مرجعِ کاراکتر
model_id	string	شرطی	یکی از model_id یا slug
slug	string	شرطی	یکی از model_id یا slug
trigger_word	string	خیر	کلمه‌ی محرکِ کاراکتر؛ همچنین به‌عنوانِ نامِ پیش‌فرضِ کاراکتر استفاده می‌شود

نمونه‌ی درخواست

curl -X POST https://roya.hashpa.com/api/v1/characters/train \
  -H "Authorization: Bearer roya_sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images_zip_url": "https://example.com/my-face-photos.zip",
    "slug": "lora-train",
    "trigger_word": "sajad_style"
  }'

پاسخ

// 202
{
  "id": "gen_...",
  "status": "queued",
  "credits_charged": 150,
  "credits_balance": 39
}

ناهمزمان و پرهزینه است. وضعیتِ آموزش را از /api/v1/characters/{id} بگیر و پس از آماده‌شدن، همان id را به /api/v1/characters/{id} با متدِ POST بده تا نهایی شود.

GET/api/v1/characters/{id}

وضعیتِ آموزشِ کاراکتر

وضعیتِ یک کارِ آموزشِ کاراکتر را برمی‌گرداند — id همان id ایست که از /api/v1/characters/train گرفته‌ای.

پارامترِ مسیر
فیلد	نوع	الزامی؟	توضیح
id	string (uuid)	بله	آی‌دیِ کارِ آموزش (از پاسخِ /characters/train)

نمونه‌ی درخواست

curl https://roya.hashpa.com/api/v1/characters/gen_xxxxxxxx \
  -H "Authorization: Bearer roya_sk_xxxxxxxx"

پاسخ

// 200
{
  "id": "gen_...",
  "status": "done",
  "error": null,
  "finalizable": true
}

وقتی finalizable=true شد، همین id را به همین مسیر با POST بفرست تا کاراکتر نهایی و قابلِ‌استفاده شود.

POST/api/v1/characters/{id}

نهایی‌کردنِ کاراکتر

پس از تمام‌شدنِ آموزش (status=done)، کاراکتر را نهایی می‌کند و یک character_id قابلِ‌استفاده در lora_ids برمی‌گرداند. idempotent است.

پارامترِ مسیر
فیلد	نوع	الزامی؟	توضیح
id	string (uuid)	بله	همان id کارِ آموزش؛ بدنه‌ای لازم نیست

نمونه‌ی درخواست

curl -X POST https://roya.hashpa.com/api/v1/characters/gen_xxxxxxxx \
  -H "Authorization: Bearer roya_sk_xxxxxxxx"

پاسخ

// 200 یا 201
{
  "character_id": "lora_...",
  "character": {
    "id": "lora_...",
    "name": "sajad_style",
    "status": "ready",
    "created_at": "2026-07-08T12:00:00.000Z"
  }
}

اگر پیش‌تر همین کارِ آموزش نهایی شده باشد، بدونِ ساختِ رکوردِ تازه همان کاراکترِ قبلی را برمی‌گرداند (idempotent).

سایر

GET/api/v1/models

فهرستِ مدل‌ها

فهرستِ مدل‌های فعال و قیمتِ پایه‌شان را برمی‌گرداند — برای پیداکردنِ slug/model_id مناسب پیش از فراخوانیِ سایرِ نقاط.

پارامترهای کوئری‌استرینگ
فیلد	نوع	الزامی؟	توضیح
section	string	خیر	فیلترِ بخش (مثلاً "image"، "video"، "tts"، "music"…)؛ اگر خالی باشد همه‌ی بخش‌ها برمی‌گردد

نمونه‌ی درخواست

curl "https://roya.hashpa.com/api/v1/models?section=image" \
  -H "Authorization: Bearer roya_sk_xxxxxxxx"

پاسخ

// 200
{
  "count": 12,
  "models": [
    {
      "id": "mdl_...",
      "slug": "flux-pro",
      "section": "image",
      "provider": "fal",
      "name_fa": "فلاکس پرو",
      "name_en": "Flux Pro",
      "price_credits": 12
    }
  ]
}

GET/api/v1/presets

فهرستِ پریست‌های سبک

پریست‌های آماده‌ی سبک برایِ تصویر یا ویدیو را برمی‌گرداند؛ id هرکدام قابلِ‌استفاده در preset_id است.

پارامترهای کوئری‌استرینگ
فیلد	نوع	الزامی؟	توضیح
section	string	خیر	"video" برای پریست‌هایِ ویدیو؛ هر مقدارِ دیگر یا خالی → پریست‌هایِ تصویر

نمونه‌ی درخواست

curl "https://roya.hashpa.com/api/v1/presets?section=video" \
  -H "Authorization: Bearer roya_sk_xxxxxxxx"

پاسخ

// 200
{
  "section": "video",
  "count": 8,
  "presets": [
    { "id": "cinematic", "name": "سینمایی", "category": "style", "desc": "…" }
  ]
}

GET/api/v1/generations/{id}

وضعیت/نتیجه‌ی یک تولید

برایِ پیگیریِ نقاطِ ناهمزمان (ویدیو، صدا، لب‌سینک، اپ‌ها، آموزشِ کاراکتر…) — وضعیت و در پایان، آدرسِ خروجی را برمی‌گرداند.

پارامترِ مسیر
فیلد	نوع	الزامی؟	توضیح
id	string (uuid)	بله	آی‌دیِ generation که در پاسخِ نقطه‌ی اصلی گرفته‌ای

نمونه‌ی درخواست

curl https://roya.hashpa.com/api/v1/generations/gen_xxxxxxxx \
  -H "Authorization: Bearer roya_sk_xxxxxxxx"

پاسخ

// 200
{
  "id": "gen_...",
  "section": "video",
  "status": "done",
  "output_urls": ["https://.../video/....mp4"],
  "error": null,
  "credits_charged": 60
}

status معمولاً یکی از queued / running / done / error است. تا status=done صبر کن، بعد از output_urls بخوان.