本文目錄:核心解釋 | 用途與選擇 | 實作示例 | 成本與限制 | 常見問題 | 申請 Higgsfield 企業版(香港合作夥伴) | 文章參考資料
核心解釋
Higgsfield API 讓開發者以同一套認證與非同步流程,提交圖像或影片生成請求,並在完成後取得檔案網址。根據 官方文件,你向選定模型的端點發送 POST 請求後,介面會立即回傳請求識別碼,以及用於查詢狀態或取消的連結;然後以輪詢取得結果,或在完成時以 webhook 接收通知。
認證方式是在 Higgsfield Console 建立金鑰。每組憑證包含 key ID 與 secret,並以 Authorization: Key YOUR_KEY_ID:YOUR_KEY_SECRET 傳送。文件亦提到仍接受舊式 hf-api-key 與 hf-secret 標頭,但新整合應使用 Authorization。無效憑證會回傳 401。個別模型可能另有取用限制,屆時或會回傳 404、423 或 503,因此「已通過認證」並不等於「該帳戶可以使用每一個模型」。
官方明確警告:不要在瀏覽器或流動應用程式直接呼叫此 API,因為任何人只要檢查應用程式,就可能取出 secret 並使用你的帳戶。憑證應存放於密鑰管理或加密環境變數,開發與正式環境應分開,也不要把金鑰寫進網址、日誌、截圖或支援訊息;如懷疑外洩,應立即輪替。
這套做法與本站已刊出的 Higgsfield MCP 與 CLI 工作流程說明並不相同。MCP 或 CLI 適合在對話或代理工具中觸發生成;API 與 SDK 則適合把生成寫進自家後端、內部工具或產品流程。兩種路徑可以並存,但不要把其中一篇當成另一篇的替代說明。
用途與選擇
當你需要由自己的系統提交提示詞、追蹤請求,並把完成檔案存到自己的儲存空間時,API 會比逐次在網頁介面操作更合適。官方文件把整合方式分成幾種:原型或短腳本可用 SDK 的 subscribe/subscribe_async,讓客戶端代為等待結果;需要明確輪詢、查狀態或取消時,則用 submit/submit_async;若已有 request ID,可直接查 status、result 或 cancel;正式環境的事件驅動整合,則建議提交時設定 webhook,並保留狀態輪詢作復原。
官方 Python SDK 以 pip install higgsfield-client 安裝,適用於 Python 3.8 或以上,並同時提供同步與非同步介面。環境變數為 HF_KEY="your-api-key-id:your-api-key-secret"。TypeScript 方面則以 npm install @higgsfield/client 安裝,環境變數為 HF_CREDENTIALS。文件寫明 v2 TypeScript 客戶端只供伺服器端使用,並會阻擋在瀏覽器執行,目的同樣是避免憑證外洩。
企業文件指出,所有帳戶使用同一組端點,差別在於生產環境更關心的控制項:資料保留、訓練選擇退出、webhook 簽章、SAML 單一登入(文件列舉 Okta、Microsoft 與自訂)、Admin 與 Member 角色,以及可命名、設定到期時間、加上標籤並查看上次使用時間的 API 金鑰。用量分析可以美元顯示,並經 GET /models/usage 或 Console 查看;官方同時提醒,用量分析並不是帳單紀錄。部分設定,例如帳戶層級保留期、發票出帳與專用容量,需由 Higgsfield 配置,可電郵 support@higgsfield.ai 或聯絡客戶經理。
若只是想先在官方頁面了解產品與型錄,可另開Higgsfield API 介紹頁(推薦連結)。本文參考資料仍使用不帶推薦參數的官方網址,以免把引用來源改成推薦連結。
實作示例
以下是教學示例,並非本站實測紀錄。情境是:培訓或內部工具團隊想在伺服器端提交一次圖像生成,確認自己能取得請求識別碼、等待終態,並在下載檔案後離開官方暫存連結。
先在 Higgsfield Console 建立金鑰,把識別碼與密鑰放到環境變數,不要寫進原始檔或前端程式。官方 Quickstart 還建議為每次提交產生 Idempotency-Key;若提交逾時、尚未收到回應,可用同一把金鑰重試,避免重複建立請求。
export HF_API_KEY_ID="your-api-key-id"
export HF_API_KEY_SECRET="your-api-key-secret"
export IDEMPOTENCY_KEY="$(uuidgen | tr '[:upper:]' '[:lower:]')"
curl --request POST
--url https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard
--header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"
--header "Content-Type: application/json"
--header "Idempotency-Key: ${IDEMPOTENCY_KEY}"
--data '{"prompt":"A quiet alpine lake at sunrise, editorial photography"}'
官方示例的初次回應狀態為 queued,並帶有 request_id、status_url 與 cancel_url。其後可向狀態端點查詢,直至到達終態。圖像完成時,回應會包含 images 陣列中的檔案網址。其他終態包括 failed、nsfw 與 canceled。若改用 Python SDK,官方示例是呼叫 higgsfield_client.subscribe("higgsfield-ai/soul/v2/standard", arguments={"prompt":"..."});這同樣是文件中的教學寫法,不代表本站已在特定帳戶驗證輸出質素。
驗收可以用下面的清單檢查,而不是以「看起來很美」作為完成標準:
- 請求在伺服器端發出,環境變數或密鑰庫中的憑證沒有寫進版本庫、日誌或前端程式。
- 你取得
request_id,並能把狀態更新到終態之一。 - 若第一次提交沒有回應,可用同一 Idempotency-Key 重試,而不是另開一筆來歷不明的新請求。
- 完成後已把檔案下載到自己的儲存空間,並記下輸出只會保留一段有限時間。
成本與限制
官方計費說明寫明:成功的生成請求會向帳戶結餘收費,實際費用視模型與參數而定。提交前可用估計端點查詢;文件中的 {"usd":"0.094"} 只說明回應格式,不能當成所有帳戶或所有模型的牌價,必須以該帳戶當次估計為準。新存入結餘的金額,會在存入一年後到期。
狀態為 failed 或 nsfw 的請求不會收費;若在接受請求時已預留金額,會自動退回。取消只適用於處理開始之前;成功取消仍在排隊中的請求會退款。輸出檔在請求結束後會保留七日,然後刪除,狀態回應與 webhook 會包含 expires_at。若要縮短保留期,可傳送 Hf-Expires-After 標頭(最少一小時),或要求官方為帳戶設定保留期;完成後也可呼叫 DELETE /requests/{request_id} 立即刪除檔案與參數,但帳單紀錄仍會保留。
速率限制視帳戶與模型而定,並以 Console 顯示為準。主要限制是同時處理中的並行數量。超過並行上限的生成請求通常仍會被接受並進入 queued,待其中一項到達終態後才開始。排隊上限是並行上限的倍數;當排隊已滿,新請求會回傳 429,並帶有 account_queue_full 與 Retry-After,此時不會建立請求或收費。文件示例中的 limit: 40 只是回應格式說明,不能寫成所有帳戶的固定上限。成功回應目前尚未附帶剩餘額度標頭,因此仍應以儀表板為權威數字。
產品頁在 2026 年 11 月 17 日查閱時,曾說明每把金鑰一開始有 20 個並行請求,提高上限是設定變更,需要時可向官方提出。這項產品頁說明必須連同查閱日期一起理解,並且不能凌駕該帳戶 Console 的實際數字。同一日產品頁上如出現限時優惠,只代表當時展示的推廣,不應寫成長期折扣或保證優惠。
常見問題
AI Academy HK 是否 Higgsfield 官方代理?
不是。學院提供學習與培訓;企業版開通請經 Trafficholic/Timson 等合作夥伴渠道。
企業版香港如何申請?
申請 Higgsfield 企業版須經合作夥伴。香港可經 Trafficholic/Timson 洽談或申請,詳見文中的 WhatsApp 與服務頁,不要只用學院通用聯絡代替。
API、SDK 與 MCP 或 CLI 有何分別?
API 與官方 SDK 用來把生成接入自家伺服器或產品;MCP 與 CLI 較適合在對話或代理工具中觸發生成。兩者都使用帳戶配額,但整合位置不同。更完整的 MCP/CLI 步驟請見已刊出的相關教學,而不要在本篇重複寫成另一份工具說明。
生成結果會在官方端保留多久?
官方文件寫明,輸出檔在請求結束後保留七日,然後刪除,並以 expires_at 標示刪除時間。若要長期保存,應下載到自己的儲存空間。企業文件亦提到,可用標頭或帳戶設定把保留期縮短至最少一小時,或在完成後刪除該請求的檔案與參數。
可以把 API 金鑰放在網站前端嗎?
不可以。官方要求只在受信任的伺服器端使用憑證,並明確警告不要由瀏覽器或流動應用程式直接呼叫。TypeScript v2 客戶端也會阻擋在瀏覽器使用。金鑰應放在密鑰管理或加密環境變數,開發與正式環境分開保管。
申請 Higgsfield 企業版(香港合作夥伴)
個人自行註冊/試用:如要以個人或自助方式使用 Higgsfield,可經我們的推薦連結前往官方平台:前往 Higgsfield 註冊或登入。我們可能因此獲得推薦回報,你不會因此被加收費用。企業版申請、團隊培訓與合作請改用文中的 WhatsApp/夥伴查詢途徑,不要用個人註冊連結代替。
文章參考資料
Higgsfield API 產品頁:https://higgsfield.ai/higgsfield-api。查閱日期:2026 年 11 月 17 日。
Higgsfield API 文件總覽:https://docs.higgsfield.ai/docs。查閱日期:2026 年 11 月 17 日。
認證說明:https://docs.higgsfield.ai/docs/authentication.md。查閱日期:2026 年 11 月 17 日。
官方 SDK 說明:https://docs.higgsfield.ai/docs/how-to/sdk.md。查閱日期:2026 年 11 月 17 日。
Quickstart:https://docs.higgsfield.ai/docs/quickstart.md。查閱日期:2026 年 11 月 17 日。
計費與保留:https://docs.higgsfield.ai/docs/concepts/billing-and-retention.md。查閱日期:2026 年 11 月 17 日。
速率限制:https://docs.higgsfield.ai/docs/concepts/rate-limits.md。查閱日期:2026 年 11 月 17 日。
企業 API 總覽:https://docs.higgsfield.ai/docs/enterprise/overview.md。查閱日期:2026 年 11 月 17 日。
本頁僅供一般資訊與學習用途,不構成法律、投資、採購、醫療、臨床或專業意見。
學習 AI,保護你的未來。