版本歷程

API v2.21：影片成品保存 30 天，過期回 410 content_expired

• 行為更新：影片成品改由平台保存，自任務完成起 30 天內都可以下載；過期時回 410 content_expired。請求、任務物件與計費都不變。
• 一、影片成品保存 30 天
• 過去影片成品只存在後端，完成約 24 小時後就可能取不到。自本版起，任務完成時平台會存一份成品，GET /v2/videos/{id}/content 與 GET /v1/videos/{id}/content 在完成後 30 天內都從這一份回傳，內容與以前相同。
• 本版上線之前完成、而且沒有在完成後約 24 小時內取件的任務，成品已無法取回。
• 超過 30 天的成品會自動刪除，無法再下載；需要長期保存請自行下載備份。
• 二、過期回 410 content_expired（/v1 與 /v2）
• 取件時成品已超過保存期限，或平台沒能存到而後端也已經沒有，回 HTTP 410，error.code 為 content_expired。重試不會成功，請重新生成。
• /v1 以前在這種情況回後端的 500（upstream_error），現在改回 410；回應形狀仍是 {"error":{"code","message"}}，只換狀態碼與 code。/v2 以前只有部分情況回 410，現在條件一致。
• 三、前台任務列表
• 超過保存期限的任務顯示「已過期」，不再提供預覽與下載。

API v2.20：/v2 回應新增 X-AppleToken-Fields-Dropped 標頭，/v2/models 新增 include=capabilities

• 相容性更新：兩項都是新增，既有的串接不受影響、不需要改動；請求的處理方式、回應內容與計費都不變。/v1 完全不變。
• 一、X-AppleToken-Fields-Dropped 回應標頭（只在 /v2）
• 你送的參數裡，如果有平台不會轉送給上游的欄位，/v2 的回應會多這個標頭，值是這些欄位名稱，依字母排序、以逗號分隔，例如 extra_body.draft。
• 這些欄位在這次更新之前就已經不會送到上游；標頭只是讓你看得到哪些參數沒有作用。
• 沒有被略過的欄位時不會出現這個標頭。串流與非串流回應都會帶；只列由英數字與 . _ - 組成的欄位名稱，最多 64 個。
• 二、/v2/models 新增 include=capabilities
• GET /v2/models?include=capabilities 會在每個模型多一個 capabilities 物件，列出平台已登記的參數範圍。每個參數有三個欄位：spec（接受的值或數值範圍）、effect（result 會影響產出，minor 不影響產出）、mode（目前都是 shadow：平台只記錄，不會因此拒絕請求）。
• 還沒有登記的模型是空物件 {}；目前登記的主要是圖片模型，之後會陸續補上。
• 不帶 include 時，/v2/models 的回應和現在相同。

API v2.19：長輸入分段計價與語音輸入單價（2026-10-26 12:00 台北時間起生效）

• 價格調整預告：下列變動自 2026-10-26 12:00（台北時間）起生效，在那之前的請求照現行價格計費。API 的請求與回應格式不變，既有整合不需要改動。
• 以下單價都是每 100 萬 token（USD），也就是 /models 頁與 /v2/models 顯示的售價。
• 一、長輸入分段計價（19 個模型）
• 這些模型的上游依「這一次請求的輸入 token 數」分段計價：輸入超過門檻時，這一筆的輸入與輸出都改用較高的單價。門檻以內的價格和現在相同。
• ByteDance-Seed-1.8：輸入／輸出 標準 $0.25／$2，輸入超過 128K token 時 $0.5／$4
• Dola-Seed-2.0-lite：輸入／輸出 標準 $0.25／$2，輸入超過 128K token 時 $0.5／$4
• Dola-Seed-2.0-mini：輸入／輸出 標準 $0.1／$0.4，輸入超過 128K token 時 $0.2／$0.8
• Dola-Seed-2.0-pro：輸入／輸出 標準 $0.5／$3，輸入超過 128K token 時 $1／$6
• gpt-5.4：輸入／輸出 標準 $2.5／$15，輸入 272K token 以上時 $5／$22.5
• gpt-5.4-pro：輸入／輸出 標準 $30／$180，輸入 272K token 以上時 $60／$270
• gpt-5.5：輸入／輸出 標準 $5／$30，輸入 272K token 以上時 $10／$45
• gpt-5.6-luna：輸入／輸出 標準 $0.2／$1.2，輸入 272K token 以上時 $0.4／$1.8
• gpt-5.6-sol：輸入／輸出 標準 $4／$20，輸入 272K token 以上時 $8／$30
• gpt-5.6-terra：輸入／輸出 標準 $2／$12，輸入 272K token 以上時 $4／$18
• NSFW-Seed-2.0-Code：輸入／輸出 標準 $0.5／$3，輸入超過 128K token 時 $1／$6
• NSFW-Seed-2.0-lite：輸入／輸出 標準 $0.25／$2，輸入超過 128K token 時 $0.5／$4
• NSFW-Seed-2.0-mini：輸入／輸出 標準 $0.1／$0.4，輸入超過 128K token 時 $0.2／$0.8
• NSFW-Seed-2.0-pro：輸入／輸出 標準 $0.5／$3，輸入超過 128K token 時 $1／$6
• qwen3.5-plus：輸入／輸出 標準 $0.4／$2.4，輸入超過 256K token 時 $0.5／$3
• qwen3.6-plus：輸入／輸出 標準 $0.5／$3，輸入超過 256K token 時 $2／$6
• qwen3.7-flash：輸入／輸出 標準 $0.03／$0.13，輸入超過 32K token 時 $0.1／$0.4，輸入超過 256K token 時 $0.2／$0.8
• qwen3.7-plus：輸入／輸出 標準 $0.4／$1.6，輸入超過 256K token 時 $1.2／$4.8
• uncensored-gpt-5.4：輸入／輸出 標準 $2.5／$15，輸入 272K token 以上時 $5／$22.5
• 門檻是十進位（128K＝128,000 token）。gpt 系列剛好 272,000 token 也算高段，其餘模型剛好等於門檻時算標準價。qwen3.7-flash 有三段。
• 預扣用平台估算的輸入長度選段（有送 input_tokens 時取兩者較大的）；結算用上游回報的實際 prompt_tokens 選段。估在門檻下、實際在門檻上時照高段結算，所以實扣可能高於預扣。送件前可用 POST /v2/quote 確認會落在哪一段。
• 二、語音輸入改用獨立單價（4 個模型）
• 送進對話的語音（usage.prompt_tokens_details.audio_tokens）目前和一般輸入同價，生效後改照上游的語音輸入單價計費，是現在的 15 倍：
• Dola-Seed-2.0-lite：語音輸入 $3.75，輸入超過 128K token 時 $7.5（現在照一般輸入 $0.25）
• Dola-Seed-2.0-mini：語音輸入 $1.5，輸入超過 128K token 時 $3（現在照一般輸入 $0.1）
• NSFW-Seed-2.0-lite：語音輸入 $3.75，輸入超過 128K token 時 $7.5（現在照一般輸入 $0.25）
• NSFW-Seed-2.0-mini：語音輸入 $1.5，輸入超過 128K token 時 $3（現在照一般輸入 $0.1）
• 文字輸入、輸出與其他模型都不受影響。
• 快取命中的輸入 token（usage.prompt_tokens_details.cached_tokens）照一般輸入單價計費，和現在相同。
• 三、不保證遵守 max_tokens 的模型（已生效，計費不變）
• 2026-10-19 實測新增 Dola-Seed-2.0-lite、Dola-Seed-2.0-mini、NSFW-Seed-2.0-mini，名單共 14 個：ByteDance-Seed-1.8、deepseek-v4-pro、Dola-Seed-2.0-lite、Dola-Seed-2.0-mini、Dola-Seed-2.0-pro、Dola-Seed-2.1-turbo、grok-4-20-reasoning、grok-4.5、kimi-k2.7-code、kimi-k3、NSFW-Dola-Seed-2.1-turbo、NSFW-Seed-2.0-Code、NSFW-Seed-2.0-mini、NSFW-Seed-2.0-pro
• 這些模型照實際用量（回應的 usage）計費，不以 max_tokens 為上限；預扣仍以你送的 max_tokens 計算，結算金額可能高於預扣。這是既有行為，API 文件的對話章節已更新。
• 四、價格怎麼顯示
• 生效後，/models 頁、/v1/models、/v2/models 的這些模型會多出分段價格（價格區間變寬），語音輸入在 pricing.components 以 input_audio_tokens 這個單位列出。API 文件會在生效時一併更新分段說明。

API v2.17：限定點數可用於所有模型類型，並可只限上游

• 相容性更新：/v1 的請求與回應格式沒有改變；/v2 只在你的帳戶有過限定點數時多出兩個欄位（見第四點）。
• 一、限定點數適用於所有模型類型
• 對話（包含串流）、圖片、影片、後處理都會先扣限定點數，規則和以前相同：上游與模型符合範圍時先扣限定點數，不足的部分再扣一般餘額；有多筆符合時，先扣最早到期的那一筆。
• 後處理比對的上游是來源影片的那一家。
• 二、可以只限上游
• 限定點數可以只指定上游、不指定模型，代表該上游的全部模型都能使用；換成其他上游就不能使用。
• 三、扣點細節
• 實際用量超過預先凍結的金額時，超出的部分也會先扣仍在範圍內、尚未到期的限定點數。
• 請求自動改由其他上游處理時，會依實際處理的上游重新判斷能不能使用限定點數。
• 四、報價與帳戶資訊
• 報價與確認單上的「可用額度」與「是否足夠」，會一併計入這次請求可用的限定點數。
• /v2/me 新增 limited_credits：列出可用的限定點數（限用上游、限用模型、剩餘、到期時間）。限用模型為 null 代表該上游的全部模型。
• /v2/usage 每筆新增 promo_amount：這筆由限定點數支付的金額，price 仍是完整售價。
• 只有曾經拿到限定點數的帳戶，/v2/me 才會出現 limited_credits，/v2/usage 才會出現 promo_amount；其他帳戶的回應不變。/v1 不變。

API v2.16：/v1 也改為 VIP 限定——全開放模型（NSFW／uncensored 系列）需要 VIP 會員

• 全開放模型（名稱以 NSFW- 或 uncensored- 開頭的 19 個系列）原本只在 /v2 限 VIP 會員使用，自本版起 /v1 也一樣。
• 非 VIP 帳戶透過 /v1 呼叫這些模型（對話、串流、圖片、影片、報價與確認送件）會收到 HTTP 403，error.code 為 membership_required；不會扣點，也不會留下凍結。
• /v1 的錯誤格式維持原樣，只有 code 與 message；/v2 另附 model、required_plan、upgrade_url。
• 暫時無法確認會員資格時回 HTTP 503（membership_check_unavailable），請稍後再試。
• VIP 會員與其他模型不受影響，回應內容與計費都不變；/v1/models 的清單也不變。
• 要繼續使用這些模型，請升級 VIP 會員。

API v2.15：「優惠碼」「限定點數」用語統一、限定點數顯示與扣點順序、影片不再受平台排隊上限

• 相容性更新：API 的請求與回應格式沒有改變，既有整合不需要改動。
• 一、用語統一
• 「兌換券」「兌換碼」改稱「優惠碼」；「贈點」改稱「限定點數」。前台、後台、收據與文件一併更新，功能本身不變。
• 二、限定點數的顯示
• 儀表板另外顯示限定點數的餘額，與一般餘額分開。
• 帳務頁列出每筆限定點數可用的模型與到期時間；已到期、停用或用完的會歸到「已失效」，不算進可用額度。
• 用量明細新增「扣款來源」欄，標出每一筆請求由限定點數與一般餘額各付了多少。
• 三、扣點順序
• 請求的上游與模型符合限定點數的範圍時，優先扣限定點數；不足的部分再從一般餘額扣。
• 同時有多筆符合時，先扣最早到期的那一筆。
• 不符合範圍的請求照常只扣一般餘額。
• 四、目前限定點數只能用在影片模型
• 現階段限定點數只適用於影片生成；對話、圖片等其他模型會直接扣一般餘額。開放到其他模型時會另行公告。
• 五、影片排隊上限調整
• 平台不再限制同時送出的影片件數，影片送件不會再因平台的排隊上限收到 429。
• 部分上游的影片是依序生成，同時送出多支時，後送的會等比較久才完成；請以任務狀態查詢結果為準。

API v2.14：文件與模型頁標示 11 個不保證遵守 max_tokens 的模型（行為與計費不變）

• 說明更新：API 行為與計費方式都沒有改變，既有整合不需要改動。
• 2026-10-14 實測（上游 siraya，送 max_tokens: 24）發現下列 11 個模型回傳的輸出超過 max_tokens，多出來的主要是推理 token；上游不保證這些模型遵守 max_tokens：
• ByteDance-Seed-1.8、deepseek-v4-pro、Dola-Seed-2.0-pro、Dola-Seed-2.1-turbo、grok-4-20-reasoning、grok-4.5、kimi-k2.7-code、kimi-k3、NSFW-Dola-Seed-2.1-turbo、NSFW-Seed-2.0-Code、NSFW-Seed-2.0-pro
• 這些模型照實際用量（回應的 usage）計費，不以 max_tokens 為上限；預扣仍以你送的 max_tokens 計算，所以結算金額可能高於預扣。這是既有行為，這次是把它寫清楚。
• API 文件（/v1、/v2）的對話章節與這些模型的模型頁已加上說明與實測數字。

API v2.13：Siraya 部分對話模型開放 functions、logit_bias、prediction、repetition_penalty（其他模型不變）

• 相容性更新：既有整合不需要改動。沒有送這四個參數的請求，行為與過去完全相同；送到下列以外的模型，也和過去一樣被靜默忽略、不會報錯。
• 過去這四個參數對所有模型都不轉送。現在只對實測確定有作用的模型原樣轉送（/v1、/v2 都適用）：
• functions：gpt-4.1、gpt-4.1-mini、gpt-5.4、gpt-5.4-mini、gpt-5.4-nano、gpt-5.6-luna
• logit_bias、prediction：gpt-4.1、gpt-4.1-mini
• repetition_penalty：ByteDance-Seed-SC、NSFW-Seed-SC
• 平台不檢查這些參數的值，效果由模型決定；用量與費用以回應的 usage 為準。
• API 文件的對話請求欄位已同步加上這張對照表。

API v2.10：憑證 IP 白名單可以一鍵帶入 IP，存檔前會提醒是否擋到正在使用的伺服器；API 文件補上 403 ip_not_allowed

• 這是相容性更新，API 的行為與回應都沒有改變（/v1、/v2 照舊），沒有設定白名單的憑證完全不受影響。
• 快速帶入：前台「API 憑證」頁每把憑證的「IP 白名單」新增三種按鈕——「最後使用的來源 IP」（呼叫這把憑證的伺服器實際使用的 IP，最準確）、「這個瀏覽器的 IP」（你開網頁的網路；瀏覽器是 IPv6 時另有整個 /64），以及「從其他憑證複製」整份名單。按鈕只會把位址填進欄位，按「儲存白名單」才會生效。
• 存檔前防呆：如果這把憑證最近一次呼叫的來源 IP 不在新名單內，會先提醒「儲存後從那裡呼叫會立刻收到 403」，勾選「我了解，仍要儲存」才會儲存。
• 文件：API 文件新增「IP 白名單」一節，錯誤碼表補上 403 ip_not_allowed（訊息會寫出平台看到的來源 IP）。來源 IP 以平台在網路邊緣判定的連線位址為準，不採用請求自帶的 X-Forwarded-For。

API v2.9：新增 auto/ 平台代選（對話），由平台在供應同一模型的上游中選路並自動換家；文件快速開始改版

• 新增寫法：/v2/chat/completions 的 model 可以寫成 auto/<模型名稱>（例如 auto/qwen3.8-flash-next）。目前只支援對話（含串流）；影片、圖片、報價使用 auto/ 會回 400 auto_unsupported。
• 選擇規則：只從目前可用的上游中選；售價不高於上游進價的路才會被選；依這次請求的售價由低到高，同價時依上游進價，再依上架先後。
• 自動換家：只有在還沒送出任何內容之前才會換家（連線失敗、5xx、429、逾時）；串流一旦開始就不會換家，不會重複扣款。
• 回應：auto/ 的回應多一個 route 欄位，寫著實際使用的上游與模型（串流放在最後一則 chunk）；usage 一律是 prompt_tokens、completion_tokens、total_tokens（有快取或推理用量時另帶細項）。帳單與用量紀錄記的是實際使用的上游。
• 既有寫法完全不變：指定上游的「上游/模型」、模型 ID、slug 的行為與回應都和以前相同，回應不會多出 route 欄位；/v1 不受影響。
• 文件：API 文件新增「平台代選：auto/」一節。快速開始改版：第 1 步改成在主控台自助建立 API 憑證（/portal/keys），不必再向我們索取；第 2 步標明查詢模型目錄（GET /v2/models）免費，並附 Python 與 Node 範例；第 7 步的對話標示為最便宜的第一次付費呼叫，並附 Python 與 Node 範例。

API v2.8 預告：2026-10-17 起，19 個 NSFW／uncensored 系列透過 /v2 呼叫需要 VIP（/v1 不受影響）

• 這是預告，今天起行為沒有任何改變。
• 生效日：2026-10-17（台北時間）起。
• 影響範圍只有 /v2：非 VIP 帳戶透過 /v2 呼叫下列系列時，會收到 403 membership_required，回應裡附有升級網址。/v1 完全不受影響，呼叫方式、計價與回應都不變。
• VIP 會員不受影響；呼叫時一樣依點數計費。
• 文字（6）：NSFW-Dola-Seed-2.1-turbo、NSFW-Seed-2.0-Code、NSFW-Seed-2.0-lite、NSFW-Seed-2.0-mini、NSFW-Seed-2.0-pro、NSFW-Seed-SC
• 圖片（4）：NSFW-Dola-Seedream-5.0-pro、NSFW-Seedream-4.0、NSFW-Seedream-4.5、NSFW-Seedream-5.0-lite
• 影片（7）：NSFW-Seedance-1.0-pro、NSFW-Seedance-1.0-pro-fast、NSFW-Seedance-1.5-pro、NSFW-Seedance-2.0、NSFW-Seedance-2.0-fast、NSFW-Seedance-2.0-mini、NSFW-Seedance-2.5
• uncensored 文字（2）：uncensored-gpt-5.1、uncensored-gpt-5.4
• 如何成為 VIP：前台「會員方案」頁按「升級 VIP」，前往 Stripe 安全付款頁面。價格 US$20／月（以 ¥3,360 計收，含稅）。

API v2.7：HappyHorse 影片的解析度大小寫自動轉換，新增浮水印開關（不設定時行為不變）

• 這是相容性更新，不換路徑世代（/v1、/v2 照舊）。既有整合不需要改動，沒有帶 watermark 的請求行為與過去完全相同。
• HappyHorse 系列的 resolution 現在由平台自動轉成大寫再送出（720p → 720P）。過去送小寫會被後端拒絕（不扣點），現在大小寫都可以。其他模型的 resolution 原樣送出，不受影響。
• HappyHorse 系列新增 watermark 參數（JSON 布林值）：送 false 可關閉浮水印，送 true 明確開啟；不帶時沿用後端預設（有浮水印）。字串 "false" 不會被轉送，其他影片模型會忽略這個欄位。
• API 文件的「解析度與尺寸」一節與影片請求欄位表已同步更新。

API v2.6：憑證可以設定 IP 白名單，前台顯示最後使用 IP（既有憑證不受影響）

• 這是相容性更新，不換路徑世代（/v1、/v2 照舊）。IP 白名單需要自行設定才會生效，未設定的憑證行為完全不變：跟以前一樣，可以從任何 IP 呼叫；/v1 與 /v2 的回應都不變。
• 最後使用 IP：前台「API 憑證」頁在每把憑證的「最後使用」底下顯示最近一次呼叫的來源 IP（每分鐘最多更新一次）。看到不認得的 IP，請立刻換發該憑證。
• IP 白名單：在同一頁每把憑證下方的「IP 白名單」設定允許的來源 IP，可以填單一 IP 或 CIDR 網段，IPv4、IPv6 都支援，一把憑證最多 20 筆，儲存後立即生效。
• 設定後，從名單以外的 IP 呼叫會收到 403，錯誤訊息會寫出被擋下的 IP。
• 填錯了也不會被鎖在外面：前台是網頁登入，不受白名單影響，回到同一頁清空即可。
• 程式跑在 IP 會變動的環境（例如 Vercel、AWS Lambda 等 serverless 平台，或家用網路）時，不建議設定白名單。

API v2.5：VIP 會員方案開放訂閱（/v1 完全不變）

• /v1 完全不受影響：既有的端點、模型、計價與回應都不變。
• VIP 會員可以透過 /v2 與網頁使用標示 VIP 的模型系列；呼叫時仍依點數計費，月費不會轉成點數。
• 價格：US$20／月（以 ¥3,360 計收，含稅）。
• 怎麼訂閱：前台「會員方案」頁按「升級 VIP」，前往 Stripe 安全付款頁面。
• 怎麼管理或取消：在「會員方案」頁進入 Billing Portal（「更新付款方式與發票」），可以更新付款方式、查看發票與取消訂閱；取消後會用到本期結束，之後不再扣款。
• 既有付費客戶已由平台贈送 VIP 到 2026-12-31，不收費、未綁定付款方式；到期後回到 Free，點數與憑證都不受影響。
• 贈送期間如果主動訂閱（「訂閱 VIP，到期後接續」），第一次扣款會延到贈送結束時才發生，不會和贈送期間重疊。

API v2.4：影片模型揭露參數限制，錯誤與失敗多了可程式判讀的欄位（只新增欄位）

• 只影響 /v2，而且只新增欄位：既有的欄位、錯誤碼、錯誤訊息與送件結果都不變，/v1 完全不變。
• GET /v2/models 的影片模型新增 checked（平台送件前會依該模型 constraints 檢查的參數），constraints 也新增 references、sizes、combos、frameImages、referenceVideo、modes（依模式而定的限制）。
• 影片參數的 400 validation_error 新增 param、reason、value、allowed（以及 mode、errors），message 與以前逐字相同；請改用新欄位判斷要修正哪個參數。
• 任務失敗時 error.code 仍是 generation_failed；平台認得原因時，新增 error.reason（content_rejected：內容審核未通過；invalid_parameters：送件後才判定參數不合法），回呼的 data.error 同樣新增 reason。

API v2.3：Seedance 影片的估價與預扣更貼近實際用量

• 帶影片參考（input_references 含 type=video）的 Seedance-2.0-mini 與 Seedance-2.5 請求，估價（/v1/quote、/v2 估價）與送件時的預扣額度，改以「2 倍成品秒數」計算。上游會把參考影片一併計入用量，先前的估價只算成品秒數，實際扣款常是估價的 1.6～2.1 倍。
• 同兩個模型的 480p 估價改用上游實際輸出尺寸，直式（9:16）與 3:4 的估價會比先前高（最多約 37%），與實際扣款一致。
• 結算方式不變：一律依上游回報的實際用量扣款，預扣多出的部分在完成後退回。若你的餘額接近單次用量，帶影片參考的請求可能在送件時就回覆餘額不足，請預留約 2 倍估價的額度。

API v2.2：影片與後處理完成時可以自動通知（回呼）

• 在 /v2 送出影片或後處理時，可以讓平台在完成或失敗時 POST 通知你的網址；/v1 不變，仍以輪詢取件。
• 先到主控台的「Webhook 回呼」頁登記接收網址（僅限 https、443 埠，最多 5 個），可以設定預設網址；送件時也可以用 callback_url 或 callback_endpoint_id 指定。
• 每則通知帶 X-AppleToken-Signature（t=時間戳,v1=HMAC-SHA256），請用主控台給你的 secret 驗證；通知裡只有狀態與取件路徑，成品仍要帶憑證 GET。
• 接收端沒有回 2xx 時會重試 6 次（約 4 小時內）；回呼是附加的通知，輪詢仍是正式的取件方式。
• 說明：/docs#webhooks

API v2.1：評分每個帳戶一票、文字速度分兩種基準、公開評比頁

• 評分防灌票：GET /v2/models 的 rating.avg 改成每個帳戶算一票（先算每個帳戶自己的平均，再取平均），要 30 天內至少 20 則、且至少 3 個不同帳戶才公開；count 仍是總則數。評分一律要用 API 憑證，前台登入不算。
• 文字速度欄位語意變更：文字模型的 speed_p50_ms（speed_basis = first_token）改成只算串流請求的首個 chunk；非串流請求的完整回應延遲另外放在新欄位 speed_response_p50_ms，樣本數在 sample.speed_response_n。圖片、影片不受影響（speed_response_p50_ms 恆為 null）。若你拿 speed_p50_ms 比較文字模型，數值可能與先前不同：/docs#ep-models
• 新增公開評比頁 /benchmarks：不用登入就能看各模型的速度、穩定度與評分及樣本數；不顯示價格，也沒有評分入口。
• /v1 不受影響，行為與原本相同。

/v2/models 指標門檻與 speed_response_p50_ms

GET /v2/models 一節寫出四個指標的門檻（速度兩種基準各 30 筆、失敗率 30 筆、評分 20 則且至少 3 個帳戶）、新欄位 speed_response_p50_ms／sample.speed_response_n，以及評分端點的 401。

費率更新與模型下架

• 部分模型的售價已更新，最新價格請看模型目錄。
• 以下 4 個模型已下架：deepseek-v4-flash、qwen-turbo、qwen3-max、gemini-2.5-flash-image。建議改用的模型請看合作上游頁的「模型歷程」。

API v2：新增 /v2 路徑（多上游、模型 ID、請求評價）；/v1 照舊可用

• 新增 /v2 路徑：每一個端點都有 /v2 版本。同一把憑證、同一個帳戶與餘額，兩個版本都能用。
• /v1 照舊：行為與原本相同（只收裸名稱、固定使用 Siraya），既有整合不需要改任何一行；/v1 不再加新功能。
• 在 /v2，一個模型＝一家上游供應的一個模型：model 請用模型 ID（mdl_…）、slug 或「上游/模型」（例如 sailflow/qwen3.8-flash-next）；裸名稱回 400 model_ref_required，附可改用的 candidates。
• GET /v2/models 一列一個模型，帶 provider、upstream_model、售價，以及速度／穩定度／評分指標。
• /v2 的生成與報價回應帶 X-AppleToken-Route 與 X-AppleToken-Model-Id 標頭；/v2/usage、/v2/jobs 的 model 是「上游/模型」並多 model_id，對帳請以它歸戶。
• 新增請求評價：POST /v2/ratings、GET /v2/ratings/{request_id}（只在 /v2）。
• "fallback": true 在 /v2 回 400 fallback_unsupported：換一家上游就是換一個模型，請自行指定。
• 怎麼從 /v1 換過來：/docs#model-migration

文件分成 v1、v2 兩份：/docs 改為 v2，舊版保留在 /docs/v1

• /docs 改寫成 v2：所有端點路徑改為 /v2，頁首說明 /v1 照舊可用。
• 「遷移指南」改成「從 /v1 換到 /v2」：要改的兩件事（base_url 與 model），以及 /v1 會維持哪些行為。
• 收錄請求評價、選擇上游、一列一個模型的模型目錄與錯誤碼（原本預計分幾版發布，併入這一版）。
• 舊版（v1）文件保留在 /docs/v1，內容凍結為原本那份；舊連結的錨點（#routes、#ep-models…）在 /docs 照樣跳得到。
• 遷移指南：/docs#model-migration

帶影片參考時照你給的 seconds 送出；失敗時附上後端原文

• - 帶影片參考、沒指定 reference_mode（或 auto／extend／reference）時，平台照你給的 seconds 送出，不再一律改成 -1。只有 reference_mode: "edit" 仍由參考影片決定長度。
• - 後端若依 prompt 把任務判成編輯，帶具體秒數的任務會失敗（送件成功、查詢時 status: "failed"，凍結全額退還），平台不會自動重送。要編輯原片請明確帶 reference_mode: "edit"。aspect_ratio 同理，平台不會自動拿掉。
• - 失敗時 error 多帶 upstream_message：後端的原文（供應商名稱已替換），結尾的 Request id: … 完整保留，查詢時請一併提供；後端有給錯誤碼時另帶 upstream_code。送件當下被拒（例如 400）與生成中途失敗都適用。code、message 不變，既有整合不需要改。

「影片參考與長度」改成新規則；錯誤回應說明 upstream_message

• - 「影片參考與長度」模式表：沒指定模式時 seconds 照你給的值送出；edit 由平台改送 -1。新增一條說明後端判成編輯時會失敗、aspect_ratio 不會被自動拿掉、失敗時看 upstream_message。
• - 估價與送件的 seconds 欄位、reference_mode 欄位改成新規則。
• - 查詢任務與錯誤格式兩節補上 upstream_message／upstream_code 的意義，範例同步更新。
• 四個語系同步更新。

影片參考新增 reference_mode：延伸與參考生影片可以指定長度

• 帶影片參考（input_references 含 type: "video"）時，可以用新欄位 reference_mode 宣告參考影片的用法：edit（編輯）／extend（延伸）／reference（參考生影片）／auto。
• - extend、reference：輸出長度就是你送的 seconds（4–30 的整數）。延伸的成品只有新增的部分，需要完整成片請自行接上原片。
• - edit、auto 或不帶：跟以前一樣，長度由參考影片決定，seconds 只用來估價與預扣。
• - 沒有影片參考卻帶了 reference_mode、值不認得、或 extend／reference 的 seconds 不在 4–30：回 400 validation_error，不預扣。
• - prompt 的寫法要和宣告的模式一致，不一致時任務會失敗。
• 不帶 reference_mode 的請求行為完全沒變，既有整合不需要改。估價回應的 resolved 會回顯 reference_mode。

影片長度 seconds 的說明補完整；新增「影片參考與長度」

• - 估價與送件的 seconds 欄位：寫明單位是秒、代表輸出影片長度、模型沒宣告時的 1–60 範圍與超出範圍的行為，以及帶影片參考時的意義。
• - 「影片參考與長度」一節改寫成 reference_mode 的模式表（用途、seconds、輸出長度）。
• - 更正：刪掉素材資產一章「帶影片參考時 seconds 必須是 -1」這句錯誤說法。它和同一份文件「seconds 仍然必填、用來估價」的說法互相矛盾，照做反而會估不出價。
• 四個語系同步更新。

影片素材被後端拒收時，錯誤訊息會指出是哪一條規格

• POST /v1/assets 上傳影片被後端拒收時，過去只會拿到 502 upstream_error 加一句「upstream service error」，看起來像服務故障。現在 message 會寫明原因與這支影片的實際規格，例如「幀率 18 fps 不在 24–60 fps 之間」。
• 回應多一個 details 欄位：details.reasons 是代碼陣列（video_fps_out_of_range／video_pixels_out_of_range／video_aspect_out_of_range／video_side_out_of_range／video_too_short），details.video 是讀到的寬高、幀率、秒數，供程式分流。
• status 與 code 沒有改變（仍是 502 upstream_error），既有的錯誤處理不必調整。上傳流程也沒有改變：平台不會替後端預先擋件，檔案一律照常送出，由後端判定。
• 後端對參考影片的規格：幀率 24–60 fps、總像素 640×640～3326×2494、長寬比 0.4–2.5、單邊 300–6000 px、長度至少 2 秒；上限依模型。最常踩到的是幀率——匯出時改成 24、25 或 30 fps 即可，解析度不必動。
• 規格全部合格卻仍被拒、或檔案讀不出規格（例如 webm）時，message 退回通用版並列出該檢查的項目，沒有 details。

新增「影片參考素材的規格與拒收訊息」

• 影片生成一章新增「影片參考素材的規格與拒收訊息」：後端對參考影片的幀率、像素數、長寬比、邊長與長度要求，以及被拒收時 message 與 details.reasons 的形狀與範例。
• 素材資產一章的限制表新增「影片規格」列，錯誤表新增 502 列。
• 四個語系同步更新。

影片模型限時特價：Seedance 2.0 Mini／Fast（含 NSFW 版）

• Seedance-2.0-mini、NSFW-Seedance-2.0-mini 每百萬 token $2.1 → $0.735（3.5 折）
• Seedance-2.0-fast、NSFW-Seedance-2.0-fast 每百萬 token $3.3 → $1.65（5 折）
• 活動至 2026-09-30 23:59（UTC） 止，到期自動恢復原價。
• 折扣已直接反映在費率上，不需要任何設定，期間內的每一次呼叫都是折扣價。

圖片生成新增 watermark：平台預設不加浮水印

• 圖片端點新增選填的 watermark（布林）。Seedream 系列的模型原廠會在圖片右下角加上「AI generated」的圓角框標記，本平台預設把它關掉——不帶這個欄位時，回來的圖沒有標記。
• 要加上標記就送 "watermark": true。這是逐次請求的設定，沒有帳號層級的開關。
• 行為變更：對不支援 watermark 的模型送這個欄位現在會回 400，過去是靜默忽略。支援與否可查 /v1/models 的 constraints.watermark。
• size 超出範圍時的錯誤訊息改為同時列出面積上下限；過去只講下限，送太大的圖被擋下時訊息會把人導向相反的方向。

浮水印說明、檔案傳輸上限，以及兩處與實作不符的更正

• 本次只修訂文件，端點行為的變更請看同日的 API v1.6。
• 新增
• - 「浮水印：本平台預設關閉」說明區塊，以及請求欄位表裡的 watermark。
• 更正兩處與實作不符的敘述
• - 「一次請求最多內嵌 10 個檔案」只適用影片端點。圖片端點的上限是「該模型接受幾張輸入圖」（constraints.maxInputImages，各模型 0～14 不等），與是不是內嵌無關。
• - 補上：response_format: "url" 回的圖片連結24 小時後失效。它是有簽章、有到期時間的暫時連結，存進資料庫當長期網址會在隔天集體失效。
• 補充
• - 走公開網址就沒有平台的大小限制：20 MB／24 MB 只約束「內嵌 base64」這條路，位元組不經過平台時不受它們約束。

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

• 送件時新增選填的 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 失敗，但不影響原片的交付與計費。

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

• 先看這三項——它們可能需要你調整整合。
• 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，不必再自己查一次餘額。
• 修正：確認送件遇到餘額不足時，報價單不再卡死。

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

• 本次只修訂文件，端點行為的變更請看同日的 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/，只有端點路徑改變時才進位；文件版本只是說明與範例的修訂。

圖片生成 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，錯誤形狀與平台其他錯誤一致。正常整合不會碰到這個上限。

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

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

版本歷程獨立成頁

• 版本歷程從 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。
• 金額改以定點整數運算，回應不再出現浮點尾差。
• 影片端點的請求與回應形狀完全不變，既有整合不需要修改。

首次發布

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