پرش به مطلب اصلی

مدل‌های تصویر و ویدئوی Higgsfield

گدارAI مدل‌های به‌روز تصویر و ویدئوی Higgsfield (Seedance 2.5، Wan 3.0، MiniMax H3، Soul 2، Recraft 4.1، Qwen Image 3، Ideogram 4 و Z-Image) را از همان مسیرهای سازگار با OpenAI ارائه می‌کند:

  • تصویر: POST /v1/images/generations و POST /v1/images/edits
  • ویدئو: POST /v1/videos، GET /v1/videos/{id}، GET /v1/videos/{id}/content، GET /v1/videos، DELETE /v1/videos/{id} و POST /v1/videos/edits

این راهنما بر اساس مستندات رسمی Higgsfield و صفحهٔ هر مدل که در ۱۴ آبان ۱۴۰۵ بازبینی شده‌اند نوشته شده است. قرارداد پارامترهای هر مدل، دقیقاً همان «Complete JSON schema» صفحهٔ رسمی آن مدل است.

انتخاب مدل​

شناسهٔ مدل در گدارAI همان Endpoint ID رسمی Higgsfield است که / در آن با - جایگزین شده است؛ مثلاً alibaba/wan-3.0/text-to-video در گدارAI می‌شود alibaba-wan-3.0-text-to-video.

نوعشناسهٔ مدل در گدارAIتوضیح
تصویرhiggsfield-ai-soul-v2-standard، higgsfield-ai-soul-cinemaSoul 2 و Soul Cinema؛ تا ۴ تصویر در هر درخواست (n)
تصویرrecraft-v4.1-text-to-image، recraft-v4.1-pro-text-to-imageRecraft 4.1
تصویرalibaba-qwen-image-3-text-to-image، alibaba-qwen-image-3-editساخت و ویرایش تصویر
تصویرideogram-v4.0، z-image-turbo، xai-grok-imagine-image-2.0Ideogram 4، Z-Image Turbo و Grok Image 2
ویدئوbytedance-seedance-2.5-image-to-video، bytedance-seedance-2.5-reference-to-videoتصویر و مرجع به ویدئو با Seedance 2.5
ویدئوbytedance-seedance-2.5-video-editویرایش ویدئو با Seedance 2.5
ویدئوalibaba-wan-3.0-text-to-videoمتن به ویدئو با Wan 3.0
ویدئوminimax-h3-image-to-videoتصویر به ویدئو با MiniMax H3

فهرست کامل پارامترهای هر مدل در کاتالوگ مدل‌ها نمایش داده می‌شود.

ساخت حساب ارائه‌دهنده​

  1. در Higgsfield Console یک API key بسازید. هر کلید از دو بخش تشکیل شده است: Key ID و Secret.
  2. در پنل مدیریت، بخش «اتصال‌دهنده‌های LLM» را باز کنید و ارائه‌دهندهٔ Higgsfield را انتخاب کنید.
  3. کلید را به شکل KEY_ID:KEY_SECRET وارد کنید؛ همان قالبی که SDKهای رسمی Higgsfield استفاده می‌کنند.
  4. تست اتصال را اجرا کنید. این تست فقط وضعیت یک درخواست ناموجود را می‌خواند و هیچ هزینه‌ای ندارد.

گدارAI فقط میزبان رسمی api.higgsfield.ai را می‌پذیرد و کلید را هرگز به کاربر یا میزبان فایل‌ها نمی‌فرستد.

قیمت‌گذاری​

Higgsfield برای مدل‌هایش جدول قیمت ثابت منتشر نمی‌کند و پاسخ وضعیت درخواست هم هزینه را برنمی‌گرداند. برای همین گدارAI برای هر درخواست:

  1. همان بدنهٔ نهایی را به POST /estimate/{endpoint_id} می‌فرستد و قیمت دقیق را از خود Higgsfield می‌گیرد.
  2. همین مبلغ را پیش از ارسال رزرو می‌کند. اگر برآورد در دسترس نباشد، درخواست ارسال نمی‌شود.
  3. اگر درخواست با completed تمام شود، دقیقاً همان مبلغ برآورد را یک بار تسویه می‌کند.
  4. اگر درخواست failed، nsfw یا canceled شود، کل رزرو آزاد می‌شود؛ Higgsfield هم برای این حالت‌ها هزینه‌ای نمی‌گیرد.

هزینه به مدل و پارامترها (مدت، کیفیت، تعداد تصویر و …) بستگی دارد. هدر هزینه در پاسخ ساخت درخواست، مبلغ رزروشده را نشان می‌دهد.

تولید تصویر​

درخواست تصویر همگام است: گدارAI کار را در Higgsfield ثبت می‌کند، تا حداکثر ۱۲۰ ثانیه منتظر می‌ماند و تصویر را به صورت b64_json برمی‌گرداند. نشانی فایل‌های Higgsfield هیچ‌وقت به کاربر داده نمی‌شود.

import time

from openai import OpenAI

client = OpenAI(base_url="https://YOUR_WORKSPACE.godarai.ir/v1", api_key="YOUR_GODARAI_TOKEN")

result = client.images.generate(
model="higgsfield-ai-soul-v2-standard",
prompt="Editorial portrait in soft daylight",
n=1,
extra_body={"aspect_ratio": "3:4", "resolution": "1080p"},
)
image_base64 = result.data[0].b64_json
  • به‌جای size از پارامترهای خود مدل مانند aspect_ratio و resolution استفاده کنید؛ Higgsfield نگاشتی از size به این پارامترها مستند نکرده است.
  • response_format فقط b64_json است.
  • n بیشتر از ۱ فقط در مدل‌هایی که batch_size دارند (Soul) پذیرفته می‌شود.
  • اگر تولید بیش از زمان انتظار طول بکشد، خطای generation_pending با شناسهٔ کار برمی‌گردد. کار در پس‌زمینه ادامه پیدا می‌کند و فقط در صورت تکمیل هزینه دارد.

ویرایش تصویر (مثلاً alibaba-qwen-image-3-edit) با client.images.edit و فایل تصویر انجام می‌شود؛ گدارAI فایل را از مسیر بارگذاری رسمی Higgsfield ارسال می‌کند.

تولید ویدئو​

video = client.videos.create(
model="alibaba-wan-3.0-text-to-video",
prompt="A cinematic wide shot of ocean waves at sunset",
seconds="8",
extra_body={"resolution": "1080p", "aspect_ratio": "16:9", "generate_audio": True},
)

while video.status in ("queued", "in_progress"):
time.sleep(10)
video = client.videos.retrieve(video.id)

if video.status == "completed":
client.videos.download_content(video.id).write_to_file("waves.mp4")
  • seconds به پارامتر duration همان مدل نگاشت می‌شود و باید در بازهٔ مستند مدل باشد.
  • input_reference (فایل در درخواست multipart یا {"image_url": "https://..."}) به ورودی تصویر همان مدل (image_url، first_frame_url یا image_urls) نگاشت می‌شود.
  • برای ویرایش ویدئو در Seedance 2.5، شناسهٔ یک ویدئوی کامل‌شدهٔ خودتان را در video: {"id": "..."} بفرستید.
  • DELETE /v1/videos/{id} کاری را که هنوز در صف است در Higgsfield لغو می‌کند و رزرو آن آزاد می‌شود. کاری که شروع شده قابل لغو نیست و طبق نتیجه تسویه می‌شود.

محدودیت‌ها و خطاها​

  • پارامترهای ناشناخته، مقدارهای خارج از بازه یا خارج از فهرست مجاز، و null در جاهایی که مدل اجازه نمی‌دهد، پیش از هر برآورد یا رزروی رد می‌شوند.
  • custom_reference_id در Soul به دارایی‌های حساب مشترک ارائه‌دهنده اشاره می‌کند و در گدارAI در دسترس نیست.
  • ورودی‌های رسانه‌ای باید نشانی عمومی HTTPS یا فایل بارگذاری‌شده باشند.
  • خطای 429 با کد account_queue_full یعنی صف حساب Higgsfield پر است؛ بعد از مدت Retry-After دوباره تلاش کنید.
  • فایل‌های خروجی در Higgsfield هفت روز پس از پایان کار حذف می‌شوند؛ ویدئو را پس از تکمیل دانلود و نگهداری کنید.