Extensions/ComfyUI-DMXAPI
ComfyUI Extension

ComfyUI-DMXAPI

封裝 DMXAPI（www.dmxapi.cn）圖像／影片生成服務的 ComfyUI 自訂節點包，純 API 客戶端，不做本地推論。

By mch000534·Created about a month ago·Updated 2 days ago· 0
mch000534/ComfyUI-DMXAPI
Nodes—
On cloudLocal install
Stars0
Updated2 days ago
Readme

ComfyUI-DMXAPI

將 DMXAPI 的圖像與影片生成服務封裝成 ComfyUI 自訂節點。

這是一個純 API 客戶端，不在本機載入或執行生成模型。目前共註冊 6 個節點：2 個圖像節點、2 個影片節點，以及 2 個不呼叫 DMXAPI 的工具節點（自我更新、設定 API Key）。節點會把 ComfyUI 的文字、圖片與影片輸入轉成 DMXAPI 請求，再將結果轉回 ComfyUI 可用的 IMAGE、VIDEO、影片路徑與 URL。

✨ 功能亮點

  • 支援 GPT Image 2／2.5 與 Agnes Image 2.1 Flash 文生圖、圖生圖。
  • MiniMax 僅支援 MiniMax-H3：整合節點完成文生影片、首幀、尾幀及首尾幀生成，另有多模態參考節點支援參考圖／影片／音訊。
  • 影片節點統一輸出 VIDEO、影格、末幀、檔案路徑、影片 URL 與任務 ID。
  • 內建非同步任務輪詢、下載、ComfyUI 影片預覽、重試與 API key 認證形式探測。
  • 參考圖會在上傳前轉成 JPEG 並限制尺寸，降低同步 API 的上傳與逾時風險。
  • 內建「自我更新」與「設定 API Key」工具節點，可在畫布上直接檢查／套用套件最新版、寫入 .env 的 API Key，不需要手動跑安裝腳本或編輯檔案。

📋 系統需求

  • ComfyUI，建議使用專案目前測試過的 Python 3.12 環境。
  • 可連線至 https://www.dmxapi.cn 的網路環境。
  • 有效的 DMXAPI API key，以及對應模型的使用權限。
  • requirements.txt 中的 Python 套件：torch、numpy、Pillow、requests、opencv-python、imageio。
  • ffmpeg 可選；當 OpenCV 與 imageio 都無法解碼時，程式可用它嘗試抽取首幀。

🚀 快速開始

安裝

將本專案放入 ComfyUI 的 custom_nodes 目錄，然後使用 ComfyUI 自己的 Python 環境安裝依賴：

cd /path/to/ComfyUI/custom_nodes/ComfyUI-DMXAPI
/path/to/ComfyUI/.venv/bin/python -m pip install -r requirements.txt

若使用 ComfyUI Desktop，請把 /path/to/ComfyUI/.venv/bin/python 替換成 Desktop 使用的虛擬環境 Python。不要用另一個沒有 torch 的系統 Python 安裝依賴。

免 Git 安裝

不想手動 git clone 或操作終端機指令的話，可以改用本專案 GitHub 頁面 提供的免 Git 安裝檔。這些安裝檔本身不含節點程式碼，執行時會即時從 GitHub 下載目前 main 分支的最新內容並解壓縮安裝，之後要更新版本只要重新執行一次即可（會詢問是否覆蓋既有資料夾）。

macOS

下載並解壓縮 install_DMXAPI_node_NOgit.zip，雙擊裡面的 install_DMXAPI_node_NOgit.app（顯示名稱「安裝 ComfyUI-DMXAPI」）。它會自動尋找同層的 install_DMXAPI_node_NOgit.command 並在「終端機」啟動安裝流程；找不到時會自動從 GitHub 下載一份再執行。

若只拿到裸的 .command 檔（沒有 .app），請改用終端機執行，並先補上執行權限與移除隔離屬性：

chmod +x install_DMXAPI_node_NOgit.command
xattr -cr install_DMXAPI_node_NOgit.command
./install_DMXAPI_node_NOgit.command

安裝腳本會自動偵測 ComfyUI 根目錄（ComfyUI Desktop 設定檔、~/Documents/ComfyUI 等常見路徑），找不到時會跳出資料夾選取視窗；也可以手動指定：

COMFYUI_ROOT="/你的/ComfyUI路徑" ./install_DMXAPI_node_NOgit.command

找到 Python 環境時會一併安裝 requirements.txt；找不到時只會複製節點檔案，需要自行安裝依賴。

Windows

直接下載並雙擊 install_DMXAPI_node_NOgit.bat。腳本會把節點下載、解壓縮到 ComfyUI Desktop 預設路徑（%USERPROFILE%\AppData\Local\Comfy-Desktop\ComfyUI-Installs\ComfyUI\ComfyUI\custom_nodes），並用同一預設路徑下 ComfyUI Desktop 內建的 Python 安裝依賴；找不到時會改用系統 python。若你的 ComfyUI 並非安裝在這個預設路徑，請改用前面「安裝」段落的手動方式。

兩種安裝檔安裝完成後都請重新啟動 ComfyUI。

設定 API key

最簡單的方式是先複製範例檔，再填入 API key。ComfyUI-DMXAPI 啟動時會自動讀取與 dmxapi_common.py 同一層的 .env：

cp .env.example .env
# 編輯 .env，填入你的 API key

可直接參考 .env.example 的欄位。

.env 是可選的；不存在時會維持原本的作業系統環境變數行為。若同一個變數同時存在於系統環境與 .env，系統環境變數優先。也可以不使用 .env，依照作業系統選擇以下指令。

macOS

只對目前 Terminal 視窗有效：

export DMXAPI_KEY="sk-your-key"

若希望之後開啟的 zsh 終端機都自動套用，可寫入 ~/.zshrc：

echo 'export DMXAPI_KEY="sk-your-key"' >> ~/.zshrc
source ~/.zshrc

若使用 ComfyUI Desktop，請在設定環境變數後完全退出並重新開啟 Desktop。若 Desktop 沒有讀到 Terminal 的環境變數，可在啟動 Desktop 前執行：

launchctl setenv DMXAPI_KEY "sk-your-key"

Windows

PowerShell：只對目前視窗有效；請從同一個視窗啟動 ComfyUI：

$env:DMXAPI_KEY = "sk-your-key"

PowerShell：永久設定目前使用者的環境變數。執行後請重新啟動 ComfyUI：

[Environment]::SetEnvironmentVariable("DMXAPI_KEY", "sk-your-key", "User")

CMD：只對目前視窗有效：

set DMXAPI_KEY=sk-your-key

CMD：永久設定目前使用者的環境變數；新的 Terminal 或 ComfyUI 程序才會讀到：

setx DMXAPI_KEY "sk-your-key"

也可以在 Windows 圖形介面開啟「系統內容 → 進階 → 環境變數」，於「使用者變數」新增 DMXAPI_KEY，再重新啟動 ComfyUI。

也可以在每個節點的 api_key 輸入欄位直接填入 key，或使用模型專屬環境變數。優先序與完整清單請見設定檔說明。

請不要把真正的 .env、API key 寫入 workflow、原始碼或 Git；.env.example 只應保留空白或示範值。

啟動

正常啟動或重新啟動 ComfyUI。ComfyUI 只會在啟動時掃描 custom_nodes/，安裝或修改節點後必須重啟。

啟動後在節點搜尋欄輸入 DMXAPI，即可找到本套件的圖像與影片節點。

📖 使用說明

圖像生成

  1. 加入 DMXAPI GPT Image 或 DMXAPI Agnes Image 2.1 Flash。
  2. 填寫 prompt，選擇模型與輸出設定。
  3. 在 api_key 填 key，或事先設定環境變數。
  4. 如需圖生圖，將 ComfyUI 的 IMAGE 接到節點的 image 輸入。
  5. 將 IMAGE 輸出接到預覽、儲存或後續工作流。

DMXAPI GPT Image 同時支援 GPT Image 2 與 2.5。純文生圖使用 /v1/images/generations JSON；帶參考圖時自動改用 /v1/images/edits multipart。2.5 純文生圖依官方預設省略 response_format，舊版 2 模型則保留 b64_json；圖片編輯不預設回傳格式，節點解析器同時接受 b64_json 與 URL。Agnes Image 2.1 Flash 的文生圖與圖生圖則都使用 /v1/images/generations，參考圖放在 extra_body.image。

GPT Image 2.5 提供以下六個模型 ID：

  • gpt-image-2.5-sunburst（品質優先）
  • gpt-image-2.5-sunburst-cdx
  • gpt-image-2.5-sunburst-ssvip
  • gpt-image-2.5-flare（節點的新預設，速度優先）
  • gpt-image-2.5-flare-cdx
  • gpt-image-2.5-flare-ssvip

上述六個型號都是使用者確認可用、由節點公開的選項。官方 2.5 頁面列出 sunburst 與 flare 基礎 ID，文生圖頁面另提及 gpt-image-2.5-sunburst-cdx 與 gpt-image-2.5-flare-cdx 的 n<=3 限制；兩個 -ssvip ID 則由使用者確認。依使用者需求，節點已為後綴變體實作與基礎型號一致的文生圖／圖片編輯端點路由，但本次未對每個後綴與兩個端點逐一進行付費冒煙測試。舊版 gpt-image-2-03、gpt-image-2、gpt-image-2-ssvip 仍保留。

quality 可選 auto、low、medium、high、xhigh、max；xhigh 與 max 僅限 2.5，舊版模型選到時會在送出請求前被本地拒絕。gpt-image-2-03 單次最多 1 張，gpt-image-2.5-sunburst-cdx 與 gpt-image-2.5-flare-cdx 單次最多 3 張，其餘模型由節點限制為最多 4 張。

GPT Image 的 size 是實際像素尺寸，支援 auto、1024x1024、1536x1024、1024x1536、2048x2048、2048x1152、3840x2160、2160x3840。

Agnes 的 size 是 1K、2K、3K、4K 檔位，ratio 另選畫面比例。參考圖 batch 最多使用前 5 張。

影片生成

影片生成節點會執行「提交任務 → 輪詢狀態 → 取得影片 URL → 可選下載」流程。生成節點的共同輸入如下：

| 輸入 | 說明 | | --- | --- | | resolution / ratio（MiniMax H3） | 直接對應上游的列舉欄位，不是像素尺寸換算。resolution 為 768P / 2K，ratio 為 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9。 | | duration | 影片秒數；送給上游前會四捨五入為整數，範圍為 4–15 秒。 | | download_video | 決定拿到影片網址後要不要把檔案下載回本機，不影響上游是否生成或計費。預設開啟：下載檔案、建立 VIDEO 輸出與節點上的內嵌播放器。關閉時 VIDEO 為 None、VIDEO_PATH 為空字串，只保留 VIDEO_URL 與 TASK_ID。 | | max_frames | 決定要不要把影片解碼成 IMAGE_FRAMES 影格序列，純粹是本機記憶體開關，與畫質無關。-1 解碼全部；0（預設）完全不解碼；大於 0 時最多解碼指定幀數。 | | save_dir | 影片保存目錄；留空時使用 ComfyUI output 目錄。想要節點上的內嵌播放器就留空。 | | poll_interval | 每隔幾秒向上游查詢一次任務狀態，預設 8 秒（可設 3–30）。輪詢查詢不計費，調小只是更早發現影片完成，一般不需要更動。 | | max_wait | 輪詢的總等待上限，預設 900 秒（15 分鐘），超過會拋 [DMXAPI Timeout]。 |

max_wait 值得特別留意：超時只代表節點放棄等待，上游任務仍在執行、而且已經計費。 生成 2K 或較長的影片時 15 分鐘不一定足夠，建議調高到 1800–3600 秒。MiniMax H3 沒有事後取件節點，超時就無法再取回該次結果。

輪詢途中的短暫網路問題不會讓整個任務前功盡棄：單次查詢失敗只會記錄警告，連續失敗 20 次才中止（以預設 8 秒間隔計算約可容忍 2.5 分鐘）。401 與 429 例外，會立即中止。

關閉 download_video 適合只想取得 URL 交給其他流程的情境。MiniMax H3 沒有事後取件節點，只能自行用 VIDEO_URL 下載，而且必須趕在上游網址失效前，因此建議維持 download_video=True。

所有影片節點的輸出固定為：

| 輸出 | 說明 | | --- | --- | | VIDEO | 可接 ComfyUI 的 SaveVideo / PreviewVideo；需要 download_video=True。 | | IMAGE_FRAMES | 依 max_frames 解碼的影格 batch。 | | LAST_FRAME | 優先使用上游的 last_frame_url；否則只在 max_frames != 0 且確實解碼到影格時取最後一幀，再無則為空白影格。 | | VIDEO_PATH | 本地影片檔案路徑。 | | VIDEO_URL | DMXAPI 回傳的影片 URL。 | | TASK_ID | MiniMax H3 非同步任務識別碼；本套件目前沒有用它事後取件的節點。 |

高解析度影片請優先保持 max_frames=0。此時即使 download_video=True、影片已保存到本地，也不會解碼 IMAGE_FRAMES 或從影片抽取 LAST_FRAME；除非上游另有提供 last_frame_url，否則兩者使用空白影格。ComfyUI 的 IMAGE 是 float32 tensor，4K 單張影格約 100 MB，15 秒 24fps 全部解碼會超過 30 GB 記憶體。

多數情況並不需要影格：VIDEO 輸出可直接接 SaveVideo / PreviewVideo，節點本身也有內嵌播放器，檔案路徑則在 VIDEO_PATH。只有要對影格本身做後製（upscale、逐幀 ControlNet、抽圖存檔、餵給其他模型）時才需要調高；只要幾張參考圖就設 8、16，真的要逐幀處理再設 -1。

若想用 LAST_FRAME 串接下一段影片，請注意 MiniMax H3 不會提供 last_frame_url，必須把 max_frames 設為 -1（或夠大的值）實際解碼到最後一幀才拿得到。

可用節點

圖像

| 顯示名稱 | 用途 | | --- | --- | | DMXAPI GPT Image | GPT Image 2／2.5 文生圖與圖生圖；內部 ID／class 為相容既有 workflow 保持 DMXAPI_GPT_Image2。 | | DMXAPI Agnes Image 2.1 Flash | Agnes Image 2.1 Flash 文生圖、多參考圖合成。 |

MiniMax

| 顯示名稱 | 用途 | | --- | --- | | DMXAPI MiniMax 影片生成 | 模型固定為 MiniMax-H3。支援四種影格組合：不接影格（文生影片）、只接 first_frame（首幀）、只接 last_frame（尾幀）、兩者都接（首尾幀）。 | | DMXAPI MiniMax 多模態參考生影片 | 模型同為 MiniMax-H3。以參考圖、參考影片與參考音訊指定主體、動作與音色，不接首尾幀（上游兩者互斥）。 |

MiniMax H3 目前沒有公開的事後取件節點。生成節點仍會回傳 TASK_ID，但無法在另一個 MiniMax ComfyUI 節點中用該 ID 事後取回影片；如需本地影片，請在生成時保持 download_video=True。

MiniMax H3 的尺寸與參數

H3 不接受任意像素尺寸。 上游只收 resolution 與 ratio 兩個列舉欄位，因此節點提供的是兩個下拉選單，不提供 width / height：

| 欄位 | 可用值 | 說明 | | --- | --- | --- | | resolution | 768P / 2K | 必填。2K 較慢也較貴。 | | ratio | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 | 只在文生影片時送出。 一旦接了 first_frame 或 last_frame，畫面比例固定跟隨輸入圖片（上游恆為 adaptive），此時節點會直接省略這個欄位。 |

早期版本曾提供 width / height 再自動換算，但 1280x720、1920x1080、1344x768 全都會換算成同一組 16:9 + 768P（2K 需要短邊約 1105 以上），造成「改了寬高卻永遠得到 1344x768」的困惑，因此改為直接選列舉。

另外兩個 DMXAPI 文件未列、但經實測確認行為的欄位：

| 欄位 | 實測結果 | | --- | --- | | prompt_optimizer（預設開啟） | 有效。 開啟時上游會先改寫、擴寫 prompt 再生成，短 prompt 的效果通常較好；關閉則嚴格照原文，適合已寫得很細的長 prompt。 | | noise_seed | 不保證可重現。 固定同一組 prompt 與 seed 連續生成兩次，得到的是兩支不同的影片。此欄位的實際用途是作為 ComfyUI 的快取鍵——改動它才會讓節點重新執行，而不是直接回傳上一次的結果。 |

MiniMax H3 多模態參考生影片

DMXAPI MiniMax 多模態參考生影片 對應上游的多模態參考生視頻介面：在 prompt 之外再給幾份「參考素材」，讓模型照著它們的主體、動作或音色生成影片。prompt 裡可以直接指名素材，例如「音色參考音頻 1」。

與首尾幀互斥。 上游明文規定：只要帶了任何一項參考素材，就不能再帶 first_frame / last_frame。因此這個節點完全沒有影格輸入；要做首尾幀請改用 DMXAPI MiniMax 影片生成。

| 輸入 | 說明 | | --- | --- | | reference_images | ComfyUI 的 IMAGE，可接 batch。節點會逐張編碼後內嵌到請求裡（JPEG、長邊縮到 2048）。 | | reference_image_urls | 公網圖片 URL，一行一個。與 reference_images 合計最多 9 張，內嵌的排在前面。 | | reference_video_1～reference_video_3 | ComfyUI 的 VIDEO，可直接接內建 Load Video。MP4／MOV 保留原檔；其他容器轉成 MP4/H.264，來源影片內的音軌會一併保留。 | | reference_audio_1～reference_audio_3 | ComfyUI 的 AUDIO，可直接接內建 Load Audio。取 batch 第一筆並轉成 PCM16 WAV。 | | reference_video_urls | 公網影片 URL（MP4／MOV），一行一個；與三個 VIDEO 插口合計最多 3 段。 | | reference_audio_urls | 公網音訊 URL（WAV／MP3），一行一個；與三個 AUDIO 插口合計最多 3 段。 |

其餘欄位（resolution、duration、noise_seed、prompt_optimizer 與下載相關的共同輸入）與 DMXAPI MiniMax 影片生成 相同，只有 ratio 不同：這裡多了 adaptive 並且是預設值，代表由上游依參考素材自動挑選最合適的比例；也可以指定 16:9 等固定比例。

其他限制與行為：

  • 參考圖片或參考影片可單獨使用，也可混合使用；參考音訊不能單獨使用，必須搭配至少一張參考圖片或一段參考影片。
  • prompt 必填且不得超過 7000 字；沒有任何參考素材時節點會直接報錯，並提示改用 DMXAPI MiniMax 影片生成。
  • 同類素材依「本機插口在前、URL 在後」合併；本機素材占滿額度後，多出的 URL 會截斷並在主控台留下警告。
  • 參考圖寬高需落在 256~5760 px、寬高比 0.4~2.5，超出範圍時節點會警告（實際判定仍在上游）。
  • 本機影片與音訊皆須單段 2～15 秒，且影片與音訊各自合計不超過 15 秒；本機單一影片上限 50 MB、單一音訊上限 15 MB。
  • 完整 JSON 請求體（含 base64 膨脹後的圖片、影片、音訊）上限 64 MB。大型素材建議改用公網 URL；URL 素材的時長與大小交由上游驗證。

工具

這兩個節點不呼叫 DMXAPI，分別操作 GitHub 與本機 .env；都是 OUTPUT_NODE（沒有下游連線也能單獨執行），但輸入不變就不會重跑，不會每次 Queue 都動作。

| 顯示名稱 | 用途 | | --- | --- | | DMXAPI 節點自我更新 | 兩段式：mode="check_only"（預設）只比對本機與 GitHub main 分支的最新版本，絕不動任何檔案；mode="apply" 才會下載並套用更新。force_update 可在本機與遠端版本相同、或連不上 GitHub 比對（例如撞到限流）時強制重新下載覆蓋；只在 apply 生效，check_only 不受影響。 | | DMXAPI 設定 API Key | 把 DMXAPI_KEY 寫進 .env 並立即同步到目前的 ComfyUI 進程，不需要重啟就能生效。 |

DMXAPI 節點自我更新：apply 會保留現有的 .env 與 .git（不像 install_DMXAPI_node_NOgit.command／.bat 那樣整包覆蓋），任何本機才有、新版本沒有的檔案也會原樣保留並在主控台記一筆警告，不會被砍掉。套用後仍需重新啟動 ComfyUI 才會生效——跟改任何節點程式碼一樣，ComfyUI 只在啟動時掃描 custom_nodes/。repo_owner_repo／branch 兩個選填欄位一般不需更動，install_requirements 預設會在套用成功後重新執行 pip install -r requirements.txt。

也可以不放節點，直接在 ComfyUI 的「設定」畫面操作：分類 DMXAPI → 自我更新，有「檢查更新」與「套用更新」兩個開關（切成開啟即觸發，動作結束後會自動撥回關閉；套用前會再跳出一次確認對話框）。結果用彈出視窗顯示，跟節點走同一套 check/apply 邏輯，效果完全一致。

DMXAPI 設定 API Key：目前只支援 DMXAPI_KEY（通用 fallback），OPENAI_API_KEY／AGNES_API_KEY／MINIMAX_API_KEY 仍須依照上面「設定 API Key」一節手動編輯 .env。畫面上的欄位會被前端遮蔽成密碼樣式、執行成功後自動清空，但這無法完全避免外洩風險：ComfyUI 節點欄位值本來就會存進 workflow JSON、預設也會嵌進輸出圖片的 metadata，遮蔽只是不讓「看畫面的人」偷看到明碼。請勿分享填了真實 Key 的 workflow 檔或圖片，也不要在填值後、還沒執行就存檔。

也可以不放節點，直接在 ComfyUI 的「設定」畫面設定：分類 DMXAPI → API Key → DMXAPI_KEY，效果跟節點完全一樣（同一個 .env、同一個優先序），不需要重啟就能生效。這裡的值存在 ComfyUI 自己的使用者設定檔，不會像節點那樣被存進 workflow JSON 或圖片 metadata，是比節點更安全的入口，建議優先用這個；只有在想把「設定 Key」寫進 workflow 自動化流程時才需要用節點。

⚙️ 設定檔說明

目前沒有獨立設定檔；API key 可透過節點輸入、作業系統環境變數或專案目錄的 .env 提供。所有變數預設都是未設定。

.env 只會在套件載入時讀取一次，支援空白行、# 註解、NAME=value、export NAME=value 及單／雙引號。放置位置是：

ComfyUI/custom_nodes/ComfyUI-DMXAPI/.env

| 環境變數 | 用途 | 優先序 | | --- | --- | --- | | DMXAPI_KEY | 所有節點的通用 fallback key。 | 節點 api_key 之後 | | OPENAI_API_KEY | GPT Image 2／2.5 的專屬 fallback。 | DMXAPI_KEY 之後 | | AGNES_API_KEY | Agnes Image 2.1 Flash 的專屬 fallback。 | DMXAPI_KEY 之後 | | MINIMAX_API_KEY | MiniMax 節點的專屬 fallback。 | DMXAPI_KEY 之後 |

解析順序是：節點輸入 api_key → DMXAPI_KEY → 該模組專屬環境變數。HTTP 請求會依端點先嘗試 Bearer 或裸 key，收到 401 時自動嘗試另一種形式；401 與 429 不會進入一般重試。

🔌 API 文件

所有請求都送往 DMXAPI：https://www.dmxapi.cn。

| 方法 | 路徑 | 使用節點 | 說明 | | --- | --- | --- | --- | | POST | /v1/images/generations | GPT Image 2／2.5 純文生圖、Agnes 文生圖／圖生圖 | 同步回傳圖像資料。 | | POST | /v1/images/edits | GPT Image 2／2.5 圖生圖 | multipart/form-data，上傳參考圖檔案。 | | POST | /v1/responses | MiniMax H3 | 提交非同步任務、輪詢狀態及取得結果。 |

官方模型文件：

🧱 專案結構

| 檔案 | 內容 | | --- | --- | | __init__.py | 合併並註冊所有節點模組。 | | dmxapi_common.py | API key、HTTP 請求與重試、輪詢、tensor 編解碼、影片下載與共用影片輸出。 | | dmxapi_gpt_image2_node.py | GPT Image 2／2.5 節點；檔名與內部 DMXAPI_GPT_Image2 識別符保留以維持相容性。 | | dmxapi_agnes_image.py | Agnes Image 2.1 Flash 節點。 | | dmxapi_minimax_h3_nodes.py | MiniMax H3 的兩個節點：首尾幀整合節點與多模態參考生影片節點。 | | dmxapi_self_update.py | 自我更新節點：檢查／套用套件最新版（GitHub main 分支），保留 .env 與 .git。 | | dmxapi_set_api_key.py | 設定 API Key 節點：把 DMXAPI_KEY 寫進 .env 並立即套用到目前的 ComfyUI 進程。 | | dmxapi_server_routes.py | 給 ComfyUI 設定畫面用的 /dmxapi/api_key、/dmxapi/self_update/* 路由，分別跟設定 API Key／自我更新節點共用同一套底層邏輯。 | | web/dmxapi_set_api_key.js | 前端擴充：把設定 API Key 節點的欄位遮蔽成密碼樣式並在執行後自動清空；另外註冊 ComfyUI 設定畫面裡的 DMXAPI API Key 選項。 | | web/dmxapi_self_update.js | 前端擴充：在 ComfyUI 設定畫面加入「檢查更新」／「套用更新」兩個開關。 | | requirements.txt | Python 依賴清單。 | | pyproject.toml | 發布到 Comfy Registry 用的套件清單，發布成功後節點會自動可在 ComfyUI-Manager 搜尋到。 | | .github/workflows/publish_action.yml | 推到 main 且 pyproject.toml 有變動時，自動呼叫 Comfy-Org/publish-node-action 發布新版本；需要先在 repo 設定 REGISTRY_ACCESS_TOKEN secret。 | | LICENSE | MIT License。 |

新增節點模組時，除了定義該模組的 NODE_CLASS_MAPPINGS 與 NODE_DISPLAY_NAME_MAPPINGS，也要把模組加入 __init__.py 的 _MODULES，否則 ComfyUI 不會載入它。

❓ 常見問題（FAQ）

節點沒有出現在 ComfyUI

確認目錄是 ComfyUI/custom_nodes/ComfyUI-DMXAPI，並完全重啟 ComfyUI。可用以下指令確認註冊數量：

cd /path/to/ComfyUI/custom_nodes/ComfyUI-DMXAPI
PYTHONDONTWRITEBYTECODE=1 /path/to/ComfyUI/.venv/bin/python -c "import importlib.util,sys; p='.'; s=importlib.util.spec_from_file_location('ComfyUI_DMXAPI',p+'/__init__.py',submodule_search_locations=[p]); m=importlib.util.module_from_spec(s); sys.modules['ComfyUI_DMXAPI']=m; s.loader.exec_module(m); print(len(m.NODE_CLASS_MAPPINGS), sorted(m.NODE_CLASS_MAPPINGS))"

預期會看到 6 個節點。

收到 401 或認證失敗

確認 key 沒有多餘空白，並檢查節點 api_key 是否覆蓋了系統環境變數或 .env。若使用系統環境變數，請在啟動 ComfyUI 的同一個 shell 中設定它；修改 .env 後也必須重新啟動 ComfyUI。不同端點的認證格式可能不同，程式會在 401 時自動嘗試另一種格式。

.env 沒有生效

確認檔案名稱正確、位置是 custom_nodes/ComfyUI-DMXAPI/.env，且內容使用 NAME=value 格式。ComfyUI 必須完全重新啟動，因為 .env 只在節點模組首次載入時讀取。

圖像生成逾時或連線被上游切斷

同步圖像端點約有 60 秒回應限制。請依序嘗試：降低 quality、改用有速度優先依據的基礎型號 gpt-image-2.5-flare、指定較小的 size（如 1024x1024 或 2048x1152）、縮短 prompt，並縮小或減少參考圖。請注意請求送出後才中斷，可能代表上游已收單並計費，避免盲目重複執行。

影片沒有內嵌播放器

將 download_video 保持開啟，並讓 save_dir 留空，使影片存到 ComfyUI 的 output 目錄。前端只能直接服務 output、input 或 temp 底下的檔案；存到其他路徑時仍會回傳 VIDEO_PATH，但只顯示路徑文字。

更新後舊 workflow 的 MiniMax 節點欄位跑掉了

MiniMax 節點的 width / height 已改成 resolution / ratio 兩個下拉。ComfyUI 的 widgets_values 是依欄位順序保存的，因此舊 workflow 載入後這兩格會落回預設值（768P / 16:9），其後的 duration、noise_seed 也可能一併偏移。請重新確認這幾個欄位，或直接刪掉節點重新加入。

MiniMax 影片為什麼不論怎麼設定都是 1344x768？

這是舊版節點的行為：當時介面收 width / height 再換算成上游的比例與解析度檔位，而常見的 1280x720、1920x1080、1344x768 全都會換算成 16:9 + 768P，也就是 1344x768。現行版本已改成直接提供 resolution 與 ratio 兩個下拉；想要更大的畫面請把 resolution 選為 2K，想改變形狀請調整 ratio。

注意接了 first_frame 或 last_frame 時 ratio 不會生效，畫面比例一律跟隨輸入圖片。

固定了 seed，為什麼每次生成的影片都不一樣？

MiniMax H3 不保證可重現。實測在關閉 prompt_optimizer、固定相同 prompt 與 noise_seed 的情況下連續生成兩次，得到的仍是兩支不同的影片。noise_seed 在本套件中的實際價值是作為 ComfyUI 的快取鍵：所有輸入都相同時 ComfyUI 不會重新執行節點，改動 noise_seed 才會真正再生成一次。

影片輪詢逾時（[DMXAPI Timeout]）

代表等待時間超過 max_wait（預設 900 秒）。請調高 max_wait 至 1800–3600 秒，特別是生成 2K 或較長的影片時。請注意逾時只是節點停止等待，上游任務仍在執行且已經計費；MiniMax H3 沒有事後取件節點，因此逾時無法再取回該次結果。

多模態參考只有音訊時報錯

MiniMax H3 不接受只有 reference_audio 的參考組合。請再提供至少一張 reference_images／reference_image_urls 圖片，或一段 reference_video_1～reference_video_3／reference_video_urls 影片；只使用參考圖片則是合法的，不需要額外附加影片。

影片影格造成記憶體不足

將 max_frames 設為 0，只保留影片物件、預覽與檔案；需要後製時再設為明確的正整數。-1 會解碼全部影格，不適合高解析度長影片。

影片無法抽幀

確認已在 ComfyUI 的 Python 環境安裝 opencv-python 或 imageio，且影片檔案可正常播放。程式會依序嘗試 OpenCV、imageio，並在只要求一幀時嘗試 ffmpeg。

GPT Image 的參考圖為什麼不是直接送 JSON？

DMXAPI 的 GPT Image 2／2.5 /v1/images/generations 是純文生圖端點；帶參考圖時節點會改用 /v1/images/edits 的 multipart 檔案欄位。這與 Agnes Image 2.1 Flash 的 extra_body.image 協定不同，不能互換。

套用自我更新後節點沒有變化

DMXAPI 節點自我更新 的 apply 只負責下載並取代套件檔案，跟改任何節點程式碼一樣，需要重新啟動 ComfyUI 才會生效——ComfyUI 只在啟動時掃描 custom_nodes/。套用成功的訊息裡會提醒這件事，重啟後再確認一次版本。

檢查更新一直顯示「無法取得」／「遠端版本：無法取得」

GitHub 未登入的 API 每小時只給同一個公網 IP 60 次額度，用完就會這樣，不是故障；report 會直接顯示是額度用完還是連不上網，額度用完的話也會估算大概還要等幾分鐘恢復。如果確定 GitHub 上有新版本、不想等額度恢復，可以把 force_update 打開再執行 apply——這樣即使版本比對失敗也會強制重新下載並套用（仍會保留 .env／.git）。

設定 API Key 後，重啟 ComfyUI 就失效了

如果作業系統本身已經設定過 DMXAPI_KEY 環境變數，DMXAPI 設定 API Key 節點寫進 .env 的值在下次重啟後不會生效——系統環境變數的優先序高於 .env（見上方「設定檔說明」）。請改用作業系統層級設定該變數，或先取消系統環境變數再用這個節點。

🤝 貢獻指南

  1. 先確認新功能對現有節點輸入順序、輸出契約與既有 workflow 的相容性。

  2. 共用的認證、重試、輪詢、編解碼與影片處理應放在 dmxapi_common.py，不要在節點內重複實作。

  3. 使用 ComfyUI 的 Python 環境進行語法檢查：

    PYTHONPYCACHEPREFIX=/private/tmp/dmxapi-pycache /path/to/ComfyUI/.venv/bin/python -m py_compile __init__.py dmxapi_common.py dmxapi_agnes_image.py dmxapi_gpt_image2_node.py dmxapi_minimax_h3_nodes.py

  4. 重啟 ComfyUI，在畫布上以真實 API 請求實測，並確認新模組已加入 __init__.py 的 _MODULES。

  5. 不要在提交內容中包含 API key、生成結果或其他敏感資料。

目前專案使用 unittest 提供離線回歸測試，但沒有獨立建置或 lint 設定；提交前至少應完成單元測試、語法檢查、節點註冊冒煙測試與 ComfyUI 實測。

📄 授權

本專案採用 MIT License。重新發布或納入其他專案前，請仍先向維護者確認 DMXAPI 服務本身的使用條款（授權涵蓋這個 ComfyUI 節點包的程式碼，不涵蓋 DMXAPI 這個第三方服務的條款）。