開發者從影像生成 API 需要什麼

開發者不需要影像生成 API 來「感覺很神奇」。他們需要的是它能「照規矩運作」。

在正確的地方，最好的 API 應該是無聊的。它能接收清楚的輸入、回傳清楚的狀態、讓失敗變得容易理解，並且不迫使團隊在供應商粗糙的邊角上再做一個「第二個產品」。

工作（Job）狀態應該明確

影像生成可能需要時間。有些工作很快完成，有些會排隊，有些則會因為模型或輸入不正確而失敗。

因此，API 應該清楚地揭露工作狀態：

• accepted
• queued
• running
• completed
• failed

這些狀態讓開發者能打造誠實的使用者介面，而不是只能猜測超時原因。

錯誤應該貼近問題

含糊的錯誤會浪費時間。如果輸入太大，就要說明。如果模型不可用，就要說明。如果生成工作者（worker）失敗，就應該直接指出，而不是回傳一個泛用的「錯誤請求」。

好的錯誤訊息不需要揭露私有內容。它們需要能指出是哪個失敗的操作。

串流進度會更好

輪詢（polling）可以運作，但進度串流（stream）會讓影像工作流程的體驗好很多。使用者可以看到工作仍在進行，而應用程式也能在輸出到達時做出反應。

這對於生成是更大流程一部分的產品特別重要：編輯器、儀表板、資產管線，以及內部工具。

API 應該尊重資料

開發者也需要知道提示詞（prompts）與來源影像會被送到哪裡。如果 API 將內容傳給第三方供應商，或是用於儲存以進行訓練，這不應該被藏在細則裡。

整合的私密性只有在它背後的 API 有多私密而已。