版本歷程

音軌風格後處理：一次生成，兩支成品

• 送件時新增選填的 post_process，任務完成後平台會另外產出一支套了聲音效果的成品，原片不受影響，兩支都可取件。
• 新增 outputs 回應欄位：任務查詢會列出原片與後處理片，各自帶狀態。既有的 content 欄位意義與行為完全沒有改變。
• 取件端點新增 ?output=processed；不帶參數的行為與過去完全相同。
• 新增獨立端點 POST /v1/post-process，可對已完成的任務、上傳的素材或內嵌檔案套用效果。
• 可用風格：phone（電話）、walkie（對講機）、radio（廣播）、vinyl（老唱片）、muffled（隔壁房間）、hall（大廳迴音）、lofi_16k / lofi_24k、mute（去音軌），強度 1–5。
• 影像不會被重新編碼，只處理音軌，畫質與原片一致。
• 後處理目前不收費；若原片沒有音軌，後處理會以 no_audio_stream 失敗，但不影響原片的交付與計費。

素材資產與圖片生成的說明、以及一輪與實作對齊

• 本次只修訂文件，端點行為的變更請看同日的 API v1.4。
• 新增的章節
• - 素材資產：能做什麼（角色一致性／動作參考／換臉）、介面與限制、怎麼上傳三步。含人臉的素材為什麼必須走資產，也寫清楚了。
• - 圖片生成：POST /v1/images/generations 的完整說明。它是同步端點——一次呼叫直接拿到圖，沒有任務 id、不需要輪詢。
• 改寫
• - 送件前確認不再是獨立小節，融入 POST /v1/videos/generations 的正文，兩種送法並排講；原本分開的兩段「錯誤」也合併成一段。
• - 素材的圖片尺寸限制 300–6000 像素——這是實測發現的，後端文件沒有寫。
• 與實作對齊的修正
• - 限流的實際數值、402 的欄位名、多張報價單的做法。
• - /v1/quote 的回應範例移除了實際不會回的 seconds，補上一定會回的 estimated。同一段範例在三個地方出現，都改了。
• - /v1/models 的 modality 對照補上 image 走哪個端點。
• - 503 的說明不再叫客戶「不用換自己的 key」——那把是他帳戶綁的上游憑證。
• 版本號規則：API 版本的主版本對應網址的 /v1/，只有端點路徑改變時才進位；文件版本只是說明與範例的修訂。

素材資產、送件前確認改用旗標，以及更嚴格的參數檢查

• 先看這三項——它們可能需要你調整整合。
• 1. version 參數已移除，改用 require_confirmation
• 送件前確認不再靠 version: "2" 觸發。改成在 POST /v1/videos/generations 帶 require_confirmation: true，回應會是一張確認單，你核對後帶 quote_id 與 confirm 才真的送出。如果你的程式還在送 version，請改用新旗標。 帳戶層的「送件前確認」開關是下限，凌駕請求裡的 false。開關預設關閉，關閉時這條端點的行為完全不變。
• 2. 參數型別不再寬鬆對待
• seconds 必須是 JSON number、stream 與 generate_audio 必須是布林 true／false、temperature 必須是數字。以前送字串可能矇混過關，現在一律回 400。 特別注意 stream：任何非空字串（包含 "false"）以前都會被當成 true 而啟用串流。檢查排在凍結額度之前，所以失敗不扣款。
• 3. 參考素材的數量上限依模型而異，而且分型別計算
• Seedance-2.0／-fast／-mini：共 15 個（圖片 9、影片 3、音訊 3），不支援只給音訊，至少要有一張圖或一段影片。Seedance-2.5：共 50 個（圖片 30、影片 10、音訊 10），支援只給音訊。超出會在送件前就被擋下。
• ---
• 新增：素材資產 API
• POST /v1/assets、GET /v1/assets、GET /v1/assets/{id}、DELETE /v1/assets/{id}。
• 含人臉的參考素材，後端不接受公開網址——必須先上傳成資產，再用 asset:// 引用。角色一致性、動作參考、換臉這三種用法都需要人臉，所以都要走資產。不含人臉的素材（風景、物件、色調參考）照舊用公開網址或內嵌 data URI 即可。
• 單檔上限 20 MB；圖片長寬都必須在 300–6000 像素之間，上傳當下就會擋下，錯誤訊息會告訴你這張圖是幾乘幾、該放大還是縮小。同一個帳戶重複上傳同一份檔案會拿回同一個 id（比對檔案內容的 sha256，與檔名無關），重試是安全的。資產長期保留直到你自己刪除，與影片素材的 7 天暫存不同。
• 限流數值已明確公布
• 帶 Authorization 標頭每分鐘 600 次（以憑證分別計數），未帶憑證每分鐘 20 次（以來源 IP 計數），/healthz 不受限。超過回 429，error.code 為 rate_limited——請用它與上游節流的 upstream_error 分辨來源。
• 額度不足的錯誤會附上數字
• 402 的 error 物件現在帶 needed 與 available，不必再自己查一次餘額。
• 修正：確認送件遇到餘額不足時，報價單不再卡死。

文件修訂：對帳、模型欄位與報價單

• 本次只修訂文件內容，端點行為完全沒有變動。修正的都是文件與實際行為不符之處——照舊版文件寫的程式可能跑不出預期結果，建議對照確認。
• - /v1/usage 的對帳章節整段重寫。 舊版描述的欄位與資料模型與實際回傳不符，照著寫的對帳流程無法執行。已改為依實際回傳欄位可行的作法。
• - /v1/models 的能力欄位形狀更正。 舊版寫成攤平的欄位名，實際是包在 constraints 物件內；移除了實際不存在的欄位；模型類型的合法值與計價欄位的說明一併更正。
• - /v1/videos/{id}/content 的說明更正。 舊版說下載不會觸發結算，實際上會先刷新任務狀態，該次呼叫可能就是觸發結算的那一次（結算不會重複扣款）。
• - /v1/quote 補上報價單路徑。 帶 prompt 時回應會多出報價單欄位，舊版文件完全沒有記載。純比價的回應形狀不變。
• - 導覽選單移除一個誤列為端點的說明章節，內容仍在正文中。

圖片生成 API

• 新增端點 POST /v1/images/generations，用文字生成圖片，也可以帶參考圖做圖生圖。
• 可用模型
• 在 GET /v1/models 以 modality=image 篩選即可看到目前開放的型號。目錄只列出能真正叫用的模型——沒有列出的代表尚未開放，不會讓你串接了才發現叫不動。
• 計價：按張計費
• 每張圖一個固定價格，與提示詞長度無關。送件前可以用 POST /v1/quote 問價，n 指定張數時費用等比例增加。結算依照實際回來幾張——如果只生成了兩張，就只收兩張的錢。
• 參考圖可以直接內嵌
• 輸入圖片支援 base64 data URI，平台會自動轉存後再送出，你不需要自備公開儲存空間，行為與影片送件的素材欄位一致。
• 參數會先驗證再處理
• 尺寸、張數、參考圖數量等限制依模型而異，全部在扣款與檔案轉存之前檢查完畢。參數不合法時你會拿到 400 與明確說明，不會被扣款，也不會產生任何暫存檔案。
• 部分圖片模型尚未開放
• 少數圖片模型的計價方式目前無法精確計算，我們選擇不上架而不是估算——寧可少開幾個型號，也不要讓你收到一張算不準的帳單。這些型號會在計價支援完成後開放。
• 每個模型支援什麼，直接查得到
• GET /v1/models 的 constraints 現在會列出各圖片模型的實際能力：可用的 size、能不能給 n（以及上限）、可接受的輸入圖張數、支援的 response_format，以及有沒有 quality / background / negative_prompt / seed。可以自訂寬高的模型會多出 minPixels 與 maxPixels——總像素落在區間內就行。不必再靠送錯拿 400 來試錯。

送件前確認、內嵌檔案、目錄搜尋與請求限流

• 自 v2 以來累積的端點行為變更，一次列出。既有整合不需要改動就能繼續運作——以下每一項都是新增能力或既有行為的補強，沒有移除任何欄位。
• 送件前確認（影片）
• POST /v1/quote 帶了 prompt 時會多回一張報價單：quote_id、expires_at、payload_digest，以及 resolved——你送出的每一個參數原樣回顯，讓你在扣款前核對。確認無誤後憑 quote_id 送件。只帶模型與秒數的純比價維持原本的無狀態回應，形狀一個字都沒變。
• 內嵌檔案自動轉存
• 影片送件的素材欄位可以直接內嵌 base64 data URI，平台會自動轉存成後端抓得到的網址再送出，你不需要自備公開儲存空間。報價單的 materials 會列出每個檔案的大小、型別、sha256 與轉存後的網址——你看到的網址就是後端會去下載的那一條。請求 Body 上限因此提高到 24 MB。
• 模型目錄可以搜尋
• GET /v1/models 新增三個選填參數：modality 依類型篩選、q 關鍵字比對、limit 限制筆數。一個都不帶時的回應與先前完全相同。
• 串流錯誤事件
• stream: true 的請求若在開始輸出後失敗，現在會送出 {"object":"error", ...} 事件並以 data: [DONE] 收尾，不再無聲中斷。額度處理不變：失敗的串流全額退還。
• 額度改掛帳戶
• 額度現在屬於帳戶，名下所有憑證共用同一筆餘額。GET /v1/me 回的 balance 是帳戶餘額，不再是單一憑證的額度。新增憑證不會分走額度，撤銷憑證也不會讓額度消失。
• 請求限流
• 帶憑證的請求每分鐘 600 次，未帶憑證每分鐘 20 次，超過回 429，錯誤形狀與平台其他錯誤一致。正常整合不會碰到這個上限。

版本歷程獨立成頁

• 版本歷程從 API 文件內的表格移到獨立的 /docs/changelog，並改由後台維護——發版公告在版本上線當天就會更新，不必等整份文件重新發布。
• 文件裡原本的「版本紀錄」章節保留，改成指向這一頁；舊的 #changelog 連結仍然有效。
• 版本號分成兩條線：API 版本講的是端點行為，可能需要你調整整合；文件版本只是說明與範例的修訂，行為不變。

對話 API 與背景結算

• 結算不再依賴輪詢。 新增背景程序主動追蹤每一筆任務並完成結算或退還；租戶輪詢仍會觸發結算，兩者冪等。凍結不會再因為沒人查詢而卡在 reserved。
• 新增對話 API POST /v1/chat/completions，支援非串流與 SSE 串流，輸入與輸出分開計價；max_tokens 必填。
• 新增文字模型 ByteDance-Seed-1.8，計價單位 output_tokens，支援串流。
• GET /v1/models 新增 modality 與 context_window 欄位。
• 修正：seconds 傳字串由 500 internal_error 改為 400 validation_error「seconds 必須是數字」。
• 修正：只給 size 不再能繞過模型的解析度限制——size 的短邊會一併檢查，不符合回 400。
• 金額改以定點整數運算，回應不再出現浮點尾差。
• 影片端點的請求與回應形狀完全不變，既有整合不需要修改。

首次發布

首次發布：影片模型、估價、生成、查詢、取件、憑證與用量端點。