مدلهای تصویر و ویدئوی 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-cinema | Soul 2 و Soul Cinema؛ تا ۴ تصویر در هر درخواست (n) |
| تصویر | recraft-v4.1-text-to-image، recraft-v4.1-pro-text-to-image | Recraft 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.0 | Ideogram 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 |
فهرست کامل پارامترهای هر مدل در کاتالوگ مدلها نمایش داده میشود.
ساخت حساب ارائهدهنده
- در Higgsfield Console یک API key بسازید. هر کلید از دو بخش تشکیل شده است: Key ID و Secret.
- در پنل مدیریت، بخش «اتصالدهندههای LLM» را باز کنید و ارائهدهندهٔ
Higgsfieldرا انتخاب کنید. - کلید را به شکل
KEY_ID:KEY_SECRETوارد کنید؛ همان قالبی که SDKهای رسمی Higgsfield استفاده میکنند. - تست اتصال را اجرا کنید. این تست فقط وضعیت یک درخواست ناموجود را میخواند و هیچ هزینهای ندارد.
گدارAI فقط میزبان رسمی api.higgsfield.ai را میپذیرد و کلید را هرگز به کاربر یا میزبان فایلها نمیفرستد.
قیمتگذاری
Higgsfield برای مدلهایش جدول قیمت ثابت منتشر نمیکند و پاسخ وضعیت درخواست هم هزینه را برنمیگرداند. برای همین گدارAI برای هر درخواست:
- همان بدنهٔ نهایی را به
POST /estimate/{endpoint_id}میفرستد و قیمت دقیق را از خود Higgsfield میگیرد. - همین مبلغ را پیش از ارسال رزرو میکند. اگر برآورد در دسترس نباشد، درخواست ارسال نمیشود.
- اگر درخواست با
completedتمام شود، دقیقاً همان مبلغ برآورد را یک بار تسویه میکند. - اگر درخواست
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 هفت روز پس از پایان کار حذف میشوند؛ ویدئو را پس از تکمیل دانلود و نگهداری کنید.