正式環境串接指南
從一次試用到可恢復、可對帳的正式環境整合。
選擇模型與協定
用已認證的即時目錄選擇 enabled 與 available 均為 true 的模型，連同 inputSchema 和範例一起讀取。公開模型頁適合發現能力，不能證明帳號目前可呼叫。原生任務使用 /api/v1，相容用戶端使用 /v1；不要把控制台 Cookie 當 API Key。
在後端準備輸入
API Key 留在你的後端環境中，不放瀏覽器、行動裝置安裝包或公開儲存庫。按目前 Schema 保留欄位型別、列舉和條件分支；媒體輸入可按媒體指南使用公開 HTTPS URL 或受支援的 Base64 輸入。上傳本機檔案時，先申請上傳票據、PUT 檔案並 commit，再將回傳的 spicy:// URI 放入模型支援的欄位。更換模型後重新驗證輸入。
先報價，再受理
用完整的 model、input 與 callBackUrl 請求 jobs/quote。向使用者顯示 estimatedCost、maxCharge、currency 和 expiresAt；報價有效期為五分鐘，不佔用餘額。確認後把 quoteId 與 expectedCost 加入同一份請求。修改輸入或出現 40901 時重新報價，不能靜默接受更高金額。金額保留十進位字串，對帳使用十進位運算。
儲存業務操作與任務的關聯
傳送前持久儲存業務操作 ID、請求內容的安全指紋和 Idempotency-Key；收到回應後補存 taskId 與 request_id。同一帳號、同一把 Key、同一邏輯提交在 24 小時時間窗內重複使用原鍵。網路逾時不代表未受理。查不到結果時先恢復原提交，不能立即建立新鍵。失敗終態後的主動重試會建立新任務並按目前條件重新計價。
可靠處理回呼與結果
公網回呼接收原始位元組，驗證簽章和時間窗，再去除重複並持久儲存；及時回傳成功，將耗時工作放入自己的佇列。按任務狀態處理重複或延遲通知。回呼不可用時，用有上限的指數退避輪詢 recordInfo。HTTP 202 只表示受理；succeeded 與 settled=true 才分別確認生成結果成功和費用終結。
控制並行與留存
給每個帳號限制在途任務數，並為請求設定逾時。429 按 Retry-After 退避；不要讓所有任務每秒同時輪詢。目錄只做短期私有快取，報價不能作為永久價目表。下載網址有效 20 分鐘，生成檔案保留 14 天，上傳素材保留 1 天；需要長期儲存時及時歸檔。關閉連線不等於取消已受理任務。
上線前驗證
先驗證讀目錄、讀餘額和報價，再經你的費用確認流程做最小生成。驗證成功、參數錯誤、餘額不足、逾時後的同鍵恢復、重複回呼、過期的下載網址和預算限制。儲存 request_id、taskId、操作時間、狀態和金額以便排除問題，不收集 Key 或完整提示詞到通用日誌。