New 一對一 AI 實戰課,不設班期,直接預約 →

未分類

Higgsfield API 與 SDK:如何把圖像與影片生成接入自家系統

說明 Higgsfield 非同步 API 與官方 Python/TypeScript SDK:伺服器端認證、請求生命週期、保留與並行限制。申請企業版經 Trafficholic/Timson。AI Academy HK 並非官方代理商。

Higgsfield API 與 SDK:如何把圖像與影片生成接入自家系統|封面示意圖

本文目錄:核心解釋 | 用途與選擇 | 實作示例 | 成本與限制 | 常見問題 | 申請 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":"..."});這同樣是文件中的教學寫法,不代表本站已在特定帳戶驗證輸出質素。

驗收可以用下面的清單檢查,而不是以「看起來很美」作為完成標準:

  1. 請求在伺服器端發出,環境變數或密鑰庫中的憑證沒有寫進版本庫、日誌或前端程式。
  2. 你取得 request_id,並能把狀態更新到終態之一。
  3. 若第一次提交沒有回應,可用同一 Idempotency-Key 重試,而不是另開一筆來歷不明的新請求。
  4. 完成後已把檔案下載到自己的儲存空間,並記下輸出只會保留一段有限時間。

成本與限制

官方計費說明寫明:成功的生成請求會向帳戶結餘收費,實際費用視模型與參數而定。提交前可用估計端點查詢;文件中的 {"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,保護你的未來。

Timson Kwok 導師照片

本文作者

Timson Kwok

Timsondaily 及 TrafficHolic 創辦人|數碼市場推廣・網站開發・人工智能應用

Timson 結合媒體創作與企業營運經驗,專注協助品牌建立網上形象、接觸客戶,並將人工智能應用到日常工作。由內容策劃、網站建設,到人工智能系統及工作流程設計,他重視每個環節能否配合實際業務需要,持續運作並帶來價值。

他以自己經營的 Timsondaily 及 TrafficHolic 作為實踐起點,親自測試工具、建立流程,再根據實際成效持續優化,將累積的經驗帶到企業項目與課堂。

教學以實戰為核心,從學員的業務、現有做法及目標出發,運用親身實踐過的方法,帶領學員逐步操作、解決問題,建立能夠應用到自己工作與生意的流程。

Threads 過去 30 日檢視約 2,000 萬(2026年9月30日至10月29日)。Instagram 一星期突破 10,000 名追蹤者,並有多條爆款。YouTube 近 100,000 訂閱。以上為 Timson 自己帳號的期間表現。

查看 Timson Kwok 導師簡介與實戰背景

分享本文

AI.Academy

想把方法用在工作上?

報讀 AI Academy HK 實戰課,或先了解香港 AI 課程與企業培訓方案。

  • 易上手
  • 一對一實戰
  • 帶走作品

不確定應該從哪一堂開始?

MISA:We're here to help