AppleToken API

一把憑證，接上多個世代的影片生成模型與對話模型。額度、估價、計量與計費都在同一層完成——你不需要面對任何上游供應商的帳號、金鑰或帳單。

這個 API 是什麼

AppleToken 是一層生成服務的中介。你用我們發的憑證呼叫我們的端點，我們代為向後端算力供應商送件、把成品取回、依實際用量計費。目前提供兩類能力：影片生成（非同步任務）與對話（同步，可串流）。

基底網址

https://appletoken.app

版本前綴

/v2（本文件涵蓋的全部端點）

協定

HTTPS，HTTP/1.1

認證

Authorization: Bearer at_live_…

編碼

請求與回應一律 UTF-8 JSON（成品下載與對話串流除外）

金額單位

美元（USD）。所有價格、額度、帳務數字皆同。

三件事值得先知道

1. 費用可以在送出前算準。 影片用 POST /v2/quote，不扣額度、不呼叫後端，直接回傳這組參數會花多少錢。對話沒有估價端點，但預扣公式是公開的，見對話的預扣與串流計費。
2. 送件即預扣額度。 影片任務一旦送出就無法取消，額度會立刻凍結，等結算或退還；對話則以 max_tokens 為上限先凍結，結束後用實際用量結算。細節見額度模型。
3. 結算由平台負責，不是由你的輪詢負責。 平台有背景程序主動追蹤每一筆任務並完成結算，你查不查都不影響帳務正確性，凍結不會因為你沒查詢而卡住。你仍然應該輪詢——那是你知道任務結果、能夠取件的唯一方式。詳見結算、退還與對帳。

五分鐘上手

1. 取得憑證

登入 主控台 → API 憑證，按「建立」就能自己產生一組，不需要另外申請。格式長這樣：

at_live_9f2c81ab_kJ3nR7xQwZ0pLm5TfYbHs2VdEcAu1NgX

憑證只會在建立與換發的當下顯示一次。沒有任何端點可以再把它讀出來——遺失就只能換發，舊的立即失效。

把它設成環境變數，下面每個範例都讀 APPLETOKEN_KEY：

export APPLETOKEN_KEY="at_live_…"

2. 看看有哪些模型

取得你這張憑證可以使用的模型與現行價格。這個請求不扣額度，餘額是 0 也能打——拿來確認憑證有效、連得上：

curl https://appletoken.app/v2/models \
  -H "Authorization: Bearer $APPLETOKEN_KEY"

同一個請求的 Python 與 Node.js 寫法：

import os, requests

r = requests.get("https://appletoken.app/v2/models",
                 headers={"Authorization": "Bearer " + os.environ["APPLETOKEN_KEY"]})
print(r.status_code, len(r.json()["data"]))

const r = await fetch('https://appletoken.app/v2/models', {
  headers: { Authorization: `Bearer ${process.env.APPLETOKEN_KEY}` },
})
console.log(r.status, (await r.json()).data.length)

3. 先問價格

curl https://appletoken.app/v2/quote \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "siraya/Seedance-2.0-fast",
    "seconds": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

{
  "model": "siraya/Seedance-2.0-fast",
  "unit": "output_tokens",
  "billable": { "output_tokens": 108900 },
  "price": 0.539055,
  "estimated": false,
  "available": 20.0
}

4. 送出任務

curl https://appletoken.app/v2/videos/generations \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "siraya/Seedance-2.0-fast",
    "prompt": "清晨的漁港，漁船緩緩進港，海面反射金色晨光",
    "seconds": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

{
  "object": "video",
  "id": "job_1a2b3c4d5e6f7a8b9c0d",
  "status": "processing",
  "model": "siraya/Seedance-2.0-fast",
  "created_at": 1756300000,
  "price_reserved": 0.539055
}

5. 輪詢到完成

curl https://appletoken.app/v2/videos/job_1a2b3c4d5e6f7a8b9c0d \
  -H "Authorization: Bearer $APPLETOKEN_KEY"

{
  "object": "video",
  "id": "job_1a2b3c4d5e6f7a8b9c0d",
  "status": "completed",
  "model": "siraya/Seedance-2.0-fast",
  "seconds": 5,
  "resolution": "720p",
  "created_at": 1756300000,
  "completed_at": 1756300182,
  "content": "/v2/videos/job_1a2b3c4d5e6f7a8b9c0d/content",
  "price_charged": 0.539055
}

6. 取件

curl https://appletoken.app/v2/videos/job_1a2b3c4d5e6f7a8b9c0d/content \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -o output.mp4

quote  ──►  generations  ──►  videos/{id}  ──►  videos/{id}/content
估價         送出＋預扣額度      輪詢＋取得結果        下載 mp4
不扣額度     回 job_…            completed 才可取件    不影響額度

結算在背後獨立進行：平台的背景程序會追到每一筆任務的終局，
你的輪詢只是順手觸發同一段結算邏輯，兩者冪等。

7. 想要對話，只要一個呼叫

對話是同步的，沒有任務 id、不需要輪詢。它也是最便宜的第一次付費呼叫（一次約幾分錢），需要帳戶有餘額：主控台右上角「儲值」（最低 $10），或在同一個對話框輸入優惠碼。

curl https://appletoken.app/v2/chat/completions \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "siraya/ByteDance-Seed-1.8",
    "max_tokens": 512,
    "messages": [{ "role": "user", "content": "用三句話說明什麼是向量資料庫" }]
  }'

同一個請求的 Python 與 Node.js 寫法：

import os, requests

r = requests.post("https://appletoken.app/v2/chat/completions",
    headers={"Authorization": "Bearer " + os.environ["APPLETOKEN_KEY"]},
    json={"model": "siraya/ByteDance-Seed-1.8", "max_tokens": 512,
          "messages": [{"role": "user", "content": "用三句話說明什麼是向量資料庫"}]})
print(r.json()["choices"][0]["message"]["content"])

const r = await fetch('https://appletoken.app/v2/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.APPLETOKEN_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'siraya/ByteDance-Seed-1.8', max_tokens: 512,
    messages: [{ role: 'user', content: '用三句話說明什麼是向量資料庫' }],
  }),
})
console.log((await r.json()).choices[0].message.content)

max_tokens 和 max_completion_tokens 都是選填；建議明確設定輸出預算，方便控制預扣。未設定時，平台使用模型目錄的預設或最大輸出量估算。完整契約見 POST /v2/chat/completions。

認證

所有需要認證的端點都用同一種方式：HTTP 標頭帶 Bearer 憑證。沒有 OAuth、沒有簽章、沒有時間戳。

Authorization: Bearer at_live_9f2c81ab_kJ3nR7xQwZ0pLm5TfYbHs2VdEcAu1NgX

憑證結構

at_live_<id>_<secret>
         │      └─ 機密部分。伺服器只保存不可逆摘要，我們自己也還原不出來。
         └──────── 憑證 id，8 個十六進位字元。可公開，用於對帳與客服溝通。

保管建議

• 放在環境變數或密鑰管理服務，不要進版控、不要進前端、不要寫進設定檔。
• 永遠不要下發到瀏覽器或行動 App。憑證等同你的額度，請一律由你的後端持有並代呼叫。
• 一旦憑證出現在截圖、log、對話紀錄裡，就當作外洩處理，立即換發。
• 不同環境（正式／測試）與不同用途，建議申請不同憑證，方便分開看用量與停用。

憑證失效時的行為

/v2/* 不使用 cookie，因此沒有 CSRF 相關要求。憑證預設不綁定來源 IP，要綁定請設定下方的 IP 白名單。

IP 白名單（選用）

在前台「API 憑證」頁，每把憑證下方都可以設定「IP 白名單」。沒有設定的憑證可以從任何 IP 呼叫；設定後，只有名單內的來源 IP 能使用這把憑證，所有 API 端點都適用。

• 可以填單一 IP 或 CIDR 網段，IPv4、IPv6 都支援，一把憑證最多 20 筆，儲存後立即生效。
• 名單以外的 IP 呼叫時回 403 ip_not_allowed，訊息會寫出平台看到的來源 IP。這個檢查排在「停用／到期」之後，已停用的憑證仍然回 403 forbidden。
• 來源 IP 是平台在網路邊緣判定的連線位址，不採用你自己帶的 X-Forwarded-For。程式在 NAT、Proxy 或 VPN 後面時，要填的是對外出口的 IP。
• 不確定要填什麼：先用這把憑證從你的伺服器呼叫一次，前台會在「最後使用」底下顯示平台看到的來源 IP，白名單表單也有按鈕可以直接帶入。前台顯示的「這個瀏覽器的 IP」是你開網頁的網路，不一定是伺服器的 IP。
• 程式跑在 IP 會變動的環境（Vercel、AWS Lambda 等 serverless 平台，或家用網路）時不建議設定，除非你為它設定了固定的對外出口 IP（例如 NAT Gateway）。
• 設錯不會被鎖在外面：前台是網頁登入，不受白名單影響，回到同一頁清空即可。

請求與回應慣例

請求

• 只支援 GET、HEAD、POST。其他方法（PUT / PATCH / DELETE）沒有對應路由，會得到 404 not_found。
• POST 的 body 必須是合法 JSON 物件（最外層是 {}，不能是陣列或純量），並帶 Content-Type: application/json。型別不對會回 400「Content-Type 必須是 application/json」。
• Body 上限 24 MB（因應內嵌 data URI 檔案而提高，見內嵌檔案自動轉存）。若要傳圖片，可用可公開存取的網址，或直接內嵌 data URI。
• 未列在文件中的欄位會被靜默忽略，不會報錯。詳見建立任務的白名單說明。

回應

• 成功時直接回資料物件，沒有 {"data": …} 外層——列表型端點例外（/v2/models、/v2/jobs、/v2/usage 會包在 data 陣列裡）。
• 時間欄位一律是 Unix 秒級時間戳（整數，UTC）。
• 金額為浮點數，單位美元。平台內部以 micro-dollar（百萬分之一美元）的整數運算，回應時轉成最多 6 位小數，因此不會有浮點尾差。
• 回應一律帶 Cache-Control: no-store，請不要快取任何回應。
• 兩個端點不回 JSON：/v2/videos/{id}/content 回原始位元組；/v2/chat/completions 在 stream: true 時回 text/event-stream。

錯誤

所有錯誤共用同一個外層結構：

{
  "error": {
    "code": "quota_exceeded",
    "message": "額度不足",
    "needed": 1.25,
    "available": 0.42
  }
}

code 是穩定的機器可讀識別，請用它來分支處理；message 是給人看的，措辭可能調整。部分錯誤會附加額外欄位（上例的 needed、available），詳見錯誤碼總表。

遷移指南：從 /v1 換到 /v2（v2.0）

一個模型＝一家上游供應的一個模型。同一個名稱如果由兩家上游供應，在 AppleToken 裡就是兩個獨立的模型：各有自己的模型 ID、slug、售價，以及速度／穩定度／評分四個指標。所以請求裡的 model 必須明確指出你要的是哪一個——只寫名稱已經不夠。

舊寫法與新寫法

三種新寫法完全等價，指向同一個模型，而且在 AppleToken 內都是全域唯一的。格式互斥（ID 以 mdl_ 開頭、上游/模型含 /、slug 兩者都沒有），不會解析出兩種結果。ID 與 slug 是 AppleToken 自己的識別碼，不是上游的模型名；上游改名不會影響它們。下面三個請求打到的是同一個模型（mdl_7k2m9q4x1c 是示意用的 ID，實際的值請從 GET /v2/models 取得）：

{ "model": "mdl_7k2m9q4x1c", … }
{ "model": "sailflow-qwen3-8-flash-next", … }
{ "model": "sailflow/qwen3.8-flash-next", … }

從 GET /v2/models 取得

GET /v2/models 的一列就是一個模型，id、slug、ref 都在上面，可以直接貼進 model。family 是原本的裸名稱，只用來把同名、不同家的模型排在一起比價，不能拿來呼叫。

# 列出所有模型的 id、slug、ref 與起價
curl -s https://appletoken.app/v2/models -H "Authorization: Bearer $APPLETOKEN_KEY" | jq -r '.data[] | [.id, .slug, .ref, .pricing.from] | @tsv'

# 原本叫 qwen3.8-flash-next 的模型有哪幾家（family 只能拿來找，不能拿來呼叫）
curl -s https://appletoken.app/v2/models -H "Authorization: Bearer $APPLETOKEN_KEY" | jq -r '.data[] | select(.family == "qwen3.8-flash-next") | "\(.id)\t\(.ref)\t\(.pricing.from)"'

遷移步驟

1. 把 base_url 換成 https://appletoken.app/v2。同一把憑證、同一個帳戶與餘額在兩個版本都能用，可以一個端點一個端點慢慢換。
2. 用上面的指令，把程式裡每個裸名稱對應到你要用的那一家。同名的兩家價格與速度可能不同，請依 pricing 與四個指標挑選。
3. 在設定或資料庫裡存模型 ID（mdl_…）。三種寫法都不會變，但 ID 最短、最不容易被誤改。
4. 把請求的 model 換成新寫法。在 /v2 送裸名稱會直接回 400 model_ref_required，照回應裡的 candidates 改即可。
5. 如果你有帶 "fallback": true，把它拿掉（見下方）。
6. 對帳程式改用 model_id 歸戶（見下方）。
7. 讀 GET /v2/models 的程式改讀新形狀：default_route 與 routes[] 已移除，現在一列就是一個模型。

回應裡的 model

• 生成與報價（/v2/chat/completions 含串流、/v2/images/generations、/v2/videos/generations、/v2/quote）：回應 body 的 model 照你送的原字串回——送 ID 回 ID、送 slug 回 slug。實際用到的模型 ID 另外放在回應標頭 X-AppleToken-Model-Id；X-AppleToken-Route 照舊是「上游/模型」。
• 紀錄與查詢（GET /v2/usage、GET /v2/jobs、GET /v2/videos/{job_id}）：每一列的 model 一律是「上游/模型」，並多一個 model_id。不論當初用哪種寫法送，這裡都是同一個值，對帳請以 model_id 歸戶。v2.0 之前的舊紀錄若對不到模型，model_id 是 null，model 保留舊名稱。

fallback 已不支援

以前 "fallback": true 的意思是「這家失敗時，改走同一個模型的另一家」。現在不同家就是不同的模型——換家等於換模型，平台不會替你做這個決定。帶 "fallback": true 會回 400 fallback_unsupported（false 或不帶照常）。需要備援的話，請在你的程式裡自己改送另一個模型的 ID。

{
  "error": {
    "code": "fallback_unsupported",
    "message": "fallback 已不支援：換一家上游就是換一個模型，請自行指定要用的模型",
    "param": "fallback",
    "docs_url": "https://appletoken.app/docs#model-migration"
  }
}

錯誤回應

送裸名稱會收到 400，candidates 列出可以改用的模型，docs_url 指向這一節：

{
  "error": {
    "code": "model_ref_required",
    "message": "模型名稱必須指定上游：'qwen3.8-flash-next' 已不再接受，請改用下列其中一個（或它的 id／slug），見遷移指南",
    "param": "model",
    "candidates": [
      { "id": "mdl_7k2m9q4x1c", "slug": "sailflow-qwen3-8-flash-next", "ref": "sailflow/qwen3.8-flash-next" }
    ],
    "docs_url": "https://appletoken.app/docs#model-migration"
  }
}

• candidates 只列出這把憑證能用的模型。裸名稱若不在你的憑證白名單內，回的是 404 not_found「未知的模型」，與不存在的模型相同。
• 不存在的 ID、slug 或「上游/模型」一律回 404 not_found。
• 錯誤訊息（message）目前一律以繁體中文回傳；請以 code 分支，不要解析訊息文字。

/v1 照舊可用

/v1 維持原本的行為，既有整合不需要改任何一行：

• model 只收原本的裸名稱，固定由 Siraya 供應；「上游/模型」、模型 ID、slug 在 /v1 一律當作不存在的名稱（400「未知的模型」）。
• 回應形狀與原本相同：GET /v1/models 沒有 provider、routes 這類上游欄位，回應也不帶 X-AppleToken-Route 標頭。
• 同一把憑證在兩個版本都能用，餘額、用量與任務是同一本帳：在 /v2 產生的紀錄，/v1 的列表照樣列出（以 /v1 的形狀）。
• /v1 不會再加新功能。目前沒有排定停止日期；若要停止，會提前在版本歷程公告。

/v1 的完整說明保留在舊版（v1）文件。

模型目錄

可用的模型與價格會隨時增減，所以不列在這份文件裡—— 這裡只講不會變的協定規則。你需要知道兩件事：一個模型＝一家上游供應的一個模型， 請求裡的 model 要寫它的模型 ID、slug 或「上游/模型」（見遷移指南）， 三者都由 AppleToken 發放、永久不變；modality 決定它走哪一組端點—— video 走 /v2/videos/generations， image 走 /v2/images/generations， text 走 /v2/chat/completions， 互相呼叫會得到 400。

三種計價單位

每個模型的 pricing.unit 會告訴你它用哪一種：

有多段費率的模型，pricing.from 是最低單價、pricing.to 是最高單價。

多段費率

有些模型的單價不是固定值，會依請求的條件切換——例如帶影片參考、或解析度拉到 1080p 以上。 費率由上往下比對，第一條命中的勝出。

哪些模型有幾段、各段的條件與單價，列在 模型目錄（需登入）——那一頁直接從平台的 catalog 讀， 永遠是當下生效的數字。這裡不重複，免得兩邊對不上。 未登入時請改用 GET /v2/models，憑證即可讀取。

不確定會落在哪一段時，先呼叫 /v2/quote——它回的 price 就是實際會凍結的金額，不必自己推算。

三種輸入模式

所有影片模型共用 POST /v2/videos/generations 這一個端點，實際模式由你給的欄位決定：

參考素材的數量上限

每個模型能帶多少參考素材，寫在該模型 GET /v2/models 的 constraints 裡，請以它為準：

"constraints": {
  "maxReferences": 15,
  "references": {"image": 9, "video": 3, "audio": 3, "audioOnly": false}
}

影片參考素材的規格與拒收訊息

參考影片由生成服務在上傳當下判定，不合規會被拒收。平台不會預先擋件；被拒收時，平台會拿上傳時讀到的檔頭規格對照下表，在錯誤訊息裡指出是哪一條。宣告了參考影片規格的模型，數值見 GET /v2/models 的 constraints.referenceVideo（只揭露，平台不預先檢查）。

拒收時的回應維持 502 upstream_error（既有的錯誤處理不必改），差別在 message 會寫明原因與實際規格，並多一個 details 欄位供程式分流：

{"error": {"code": "upstream_error",
  "message": "上游拒收這份影片素材：幀率 18 fps 不在 24–60 fps 之間（請在剪輯軟體匯出時改成 24、25 或 30 fps，解析度不必改）。（這支影片是 1920x1080、18 fps、7.8 秒）",
  "details": {"reasons": ["video_fps_out_of_range"],
              "video": {"width": 1920, "height": 1080, "fps": 18, "durationSeconds": 7.78}}}}

影片參考與長度：reference_mode

當 input_references 含 type: "video" 的項目時，可以用 reference_mode 告訴後端這支參考影片要怎麼用。它決定你給的 seconds 會不會成為輸出長度：

• reference_mode 只接受上表四個字串。沒有影片參考卻帶了 reference_mode，或 extend／reference 的 seconds 不是範圍內的整數，都會回 400 validation_error（後者帶 param: "seconds"、mode）——不會被靜默忽略，也不會凍結額度。
• prompt 的寫法要和宣告的模式一致。延伸就寫「接在最後一幀之後繼續……」，編輯就寫「把 X 換成 Y」，參考生影片描述要拍的新畫面、避開「替換、保持不變、延長、繼續」這類字眼。兩者不一致時任務會以失敗告終。
• 沒指定模式（或 "auto"）時，平台照你給的 seconds 送出，不會改成 -1。生成服務若依 prompt 把任務判成編輯——編輯的長度只能由原片決定——帶了具體秒數的任務會失敗：送件照常成功，之後查詢時 status 變成 failed，凍結全額退還。平台不會自動改送或重試；要編輯原片，請明確帶 reference_mode: "edit"。同理，部分模型在延伸或編輯時比例只能跟隨原片：這類模型會在 constraints.modes.<模式>.aspectRatio 宣告 "inherit"，明確宣告該模式時帶了其他比例會直接回 400（reason: "mode_conflict"，不帶或填 "adaptive" 即可）；沒宣告模式時平台無法預知，任務可能以失敗告終。失敗時 error.upstream_message 會附上生成服務的原文，請依原文調整參數，見查詢任務。
• 延伸的成品只有新增的部分。需要「原片＋延伸」的完整成片時，請自行把兩段接起來。
• 估價（/v2/quote）接受同一個欄位，報價單的 resolved 會原樣回顯 reference_mode。
• 實際長度與最終費用以結算為準；最終金額就是 /v2/usage 那一列的 price。
• 帶影片參考時，後端的計費會把參考影片的長度也算進去，結算常高於估價。建議估高不估低，避免結算金額超過預扣造成餘額變負。

圖片素材的格式要求

• 必須是圖片檔的直連網址（結尾是實際圖片資源），不能是網頁網址。傳網頁網址會得到「格式不支援」類的失敗。
• 本機檔案無法被後端直接取得，可用 base64 data URI 內嵌——平台會自動轉存成網址再送出（見內嵌檔案自動轉存）；或先上傳到你自己可公開存取的儲存空間。
• 建議事先轉成 JPEG 並把長邊縮到 2048 以內：可同時避開格式不支援，並讓內嵌的 data URI 遠低於 20 MB 的單檔上限。

參數限制總表

長度 seconds

• 必須是數字型別（JSON number）。傳字串 "5" 會回 400 validation_error「seconds 必須是數字」——這是明確的參數錯誤，修好再送即可。
• 必須大於 0，且落在該模型允許的範圍內。部分模型只接受列舉的長度（constraints.allowedSeconds）， 其餘走區間（constraints.minSeconds / constraints.maxSeconds）。模型未宣告上限時，平台仍會套用 60 秒的硬上限—— 沒有上界的請求會凍結一筆必然被拒的金額。這時 checked 不含 seconds：60 秒以內的值平台都會送出，模型實際能不能生成，要等任務結果。
• 整數為宜。長度只由這個參數決定——在 prompt 裡寫「三十秒的影片」不會生效。

解析度 resolution 與尺寸 size

• resolution 接受 "480p"、"720p"、"1080p" 等形式，必須在該模型的支援清單內。有清單的模型請照清單的寫法送（"720p"；"720" 會被擋下）。
• HappyHorse 系列（happyhorse-…）的後端只收大寫的 "720P"、"1080P"（1.1 版另有 "480P"；1.0 版沒有 480P）。平台會自動把 resolution 轉成大寫再送出，所以送 "720p" 或 "720P" 都可以；其他模型的 resolution 原樣送出，不做轉換。
• size 可直接指定像素，格式 "1280x720"。同時提供時 size 優先決定計價用的畫面尺寸。
• token 制的模型必須至少提供 resolution 或 size 其中之一，否則無法精算用量，會回 400。

畫面比例 aspect_ratio

音訊 generate_audio

• 布林值。僅對音訊欄位標示為 ✅ 的模型有效。
• 模型的 constraints.audio 為 false 時不支援音訊；對它傳 true 不會報錯，但成品不會有聲音。 未宣告 audio 的模型，平台不保證成品有沒有音軌。
• 音訊不影響計價——費用只看畫面尺寸、影格數或秒數。

對話參數

GET /v2/models

取得模型目錄與現行價格。

一列就是一個模型（一家上游供應的一個模型）。同一個名稱由兩家上游供應，會出現兩列，各有自己的 id、slug、ref、售價與四個指標。每一列的 id、slug、ref 三個值都能直接放進請求的 model，見遷移指南。不帶任何參數時回傳完整清單；以下三個查詢參數都是選填。

Query 參數

三個參數可以自由組合，例如同時用 modality 縮小模態、q 比對關鍵字。

curl "https://appletoken.app/v2/models?modality=text&q=gpt" \
  -H "Authorization: Bearer $APPLETOKEN_KEY"

回應

{
  "object": "list",
  "data": [
    {
      "id": "mdl_3h8r5t0v6w",
      "slug": "siraya-seedance-2-0-fast",
      "ref": "siraya/Seedance-2.0-fast",
      "provider": { "id": "siraya", "label": "Siraya" },
      "name": "Seedance-2.0-fast",
      "upstream_model": "SIRAYA-Seedance-2.0-fast",
      "family": "Seedance-2.0-fast",
      "label": "Video Fast · SIRAYA",
      "description": "生成較快，成本較低",
      "modality": "video",
      "constraints": {
        "minSeconds": 4,
        "maxSeconds": 15,
        "resolutions": ["480p", "720p"],
        "audio": true
      },
      "pricing": { "unit": "output_tokens", "from": 4.95, "to": 4.95 },
      "status": "active",
      "speed_p50_ms": 38100, "speed_basis": "submit_to_complete", "speed_response_p50_ms": null,
      "fail_rate": 0.008,
      "rating": { "avg": 4.4, "count": 31 },
      "sample": { "speed_n": 180, "speed_response_n": 0, "fail_n": 180, "window_days": 7 }
    },
    {
      "id": "mdl_8f2j6n0r4v",
      "slug": "sailflow-minimax-h3",
      "ref": "sailflow/minimax-h3",
      "provider": { "id": "sailflow", "label": "Sailflow" },
      "name": "minimax-h3",
      "upstream_model": "sailflow/minimax-h3",
      "family": "minimax-h3",
      "label": "MiniMax-H3",
      "description": "含音訊。秒數 4–15；720p 實際輸出 1280×704。",
      "modality": "video",
      "constraints": {
        "minSeconds": 4,
        "maxSeconds": 15,
        "resolutions": ["576p", "720p", "1024p"],
        "aspectRatios": ["16:9", "9:16", "1:1"],
        "audio": true
      },
      "pricing": { "unit": "video_seconds", "from": 0.01, "to": 0.025 },
      "status": "active",
      "speed_p50_ms": null, "speed_basis": "submit_to_complete", "speed_response_p50_ms": null,
      "fail_rate": null,
      "rating": null,
      "sample": { "speed_n": 12, "speed_response_n": 0, "fail_n": 12, "window_days": 7 },
      "reason": { "speed": "insufficient_samples", "stability": "insufficient_samples", "rating": "no_data" }
    },
    {
      "id": "mdl_9p4d2n7e5f",
      "slug": "siraya-bytedance-seed-1-8",
      "ref": "siraya/ByteDance-Seed-1.8",
      "provider": { "id": "siraya", "label": "Siraya" },
      "name": "ByteDance-Seed-1.8",
      "upstream_model": "ByteDance-Seed-1.8",
      "family": "ByteDance-Seed-1.8",
      "label": "Chat Pro · SIRAYA",
      "description": "長上下文與複雜推理，支援串流",
      "modality": "text",
      "constraints": {
        "maxOutputTokens": 8192,
        "defaultMaxOutputTokens": 2048
      },
      "pricing": {
        "unit": "output_tokens", "from": 3, "to": 3,
        "components": [
          { "unit": "input_tokens",  "from": 0.375, "to": 0.375 },
          { "unit": "output_tokens", "from": 3,     "to": 3     }
        ]
      },
      "status": "active",
      "speed_p50_ms": 820, "speed_basis": "first_token", "speed_response_p50_ms": 2950,
      "fail_rate": 0.002,
      "rating": { "avg": 4.6, "count": 88 },
      "sample": { "speed_n": 1240, "speed_response_n": 310, "fail_n": 1550, "window_days": 7 }
    }
  ]
}

選擇上游

選上游就是選模型。直接用那一列的 id、slug 或 ref 呼叫，就會固定由那一家供應，不會換家。這條規則對 對話、圖片、影片、報價一體適用。怎麼從舊寫法改過來，見遷移指南。

例外：auto/（v2.9）。把 model 寫成 auto/<模型名稱>，由平台在提供這個模型的上游中替你選一家，失敗時自動換家。目前只支援對話，見平台代選。

回應裡怎麼知道用了哪個模型

成功的生成與報價回應都帶兩個標頭（串流是 SSE 的 200 標頭）：X-AppleToken-Route: siraya/Seedance-2.0-fast（上游/模型）與 X-AppleToken-Model-Id: mdl_3h8r5t0v6w。回應 body 的 model 照你送的原字串回。/v2/usage、/v2/jobs、/v2/videos/{job_id} 的 model 一律是「上游/模型」，並帶 model_id。

錯誤

音軌後處理跑在平台自己的服務上，不經過上游，不適用上游選擇。

內嵌檔案自動轉存

影片端點（POST /v2/videos/generations）的素材參數收的是網址，平台會把網址交給後端去下載——如果那個網址需要登入、是私有分享連結、或有防盜鏈，後端就抓不到，送件會失敗並回報「resource download failed」。若你沒有可公開存取的儲存空間，可以直接把檔案以 data URI 的形式放進素材參數——平台會在送件前自動把它存進暫存空間、換成一條可下載的網址再交給後端，呼叫方式完全不用改變。

適用的參數：影片端點（POST /v2/videos/generations）的 image_url、input_references、frame_images——巢狀在物件或陣列裡的值也會被處理；以及圖片端點（POST /v2/images/generations）的 image，那裡只收圖片型別（image/png、image/jpeg、image/webp、image/gif）。對話端點（POST /v2/chat/completions）不支援這個行為。格式為 data:image/png;base64,<base64 內容>。

• 支援的型別：image/png、image/jpeg、image/webp、image/gif、video/mp4、video/quicktime、video/webm、audio/mpeg、audio/wav、audio/mp4；每個檔案上限 20 MB，型別不支援或超過大小一律回 400 validation_error。
• 內容必須真的是宣告的型別：平台會檢查檔案開頭的識別位元組來確認實際格式，宣告 image/png 卻放進去的其實是 HTML、指令碼或其他格式，會被擋下並回 400 validation_error。
• 影片端點一次請求最多內嵌 10 個檔案，超過會回 400 validation_error。圖片端點不套這個數字——那裡的上限是「該模型接受幾張輸入圖」（查 /v2/models 的 constraints.maxInputImages，各模型 0～14 不等），與是不是內嵌無關。
• 值不是 data URI 時完全不受影響——一般網址原樣送給後端，這個功能不會改變既有整合的行為。而且走網址就沒有平台的大小限制：20 MB／24 MB 這兩道只約束「內嵌 base64」這條路，位元組不經過平台時不受它們約束（後端自己抓得動多大，由後端決定）。

POST /v2/quote

用一組參數換一個價格。不扣額度、不凍結、不送件、不呼叫後端，可以放心在使用者按下「生成」之前先呼叫，用來顯示預估費用。

請求欄位

prompt 在這個端點不是必填——只想問價格可以不給，價格本身與內容無關。但它是兩條回應路徑的分岔點：影片模型且帶了一個非空白的 prompt，回應就會多一張報價單，可以拿去確認後送件（見送件前確認）；沒帶就是單純的價格查詢。只有空白字元的 prompt 視同沒帶。

回應：兩條路徑

這個端點有兩條回應路徑，分岔只看一件事：有沒有帶 prompt。

路徑一：純比價

{
  "model": "siraya/Seedance-2.0-fast",
  "unit": "output_tokens",
  "billable": { "output_tokens": 108900 },
  "price": 0.539055,
  "estimated": false,
  "available": 20.0
}

圖片模型也走這條路徑（圖片沒有報價單，不會有 quote_id）。送出與送件相同的參數，回應形狀完全一樣：

{
  "model": "siraya/ByteDance-Seedream-4.5",
  "unit": "request",
  "billable": { "request": 2 },
  "price": 0.08,
  "estimated": false,
  "available": 20.0
}

estimated 說明這個數字的性質：按張計價的圖片模型 unit 是 "request"、estimated 為 false（精算，等於實收）；按 token 計價的圖片模型 unit 是 "output_tokens"、estimated 為 true（上限估計，實收以結算為準）。

路徑二：報價單（帶了 prompt）

回應是路徑一的全部欄位，再加上下面這些。多出來的部分是讓你在送出前核對「實際會送給後端的到底是什麼」，確認無誤再憑 quote_id 送件——回 POST /v2/videos/generations 帶上 quote_id 與 confirm 就會真的送出，完整做法見送件前確認，兩個入口產生的是同一種報價單。

{
  "model": "siraya/Seedance-2.0-fast",
  "unit": "output_tokens",
  "billable": { "output_tokens": 108900 },
  "price": 0.539055,
  "estimated": false,
  "available": 20.0,

  "quote_id": "q_a1b2c3d4e5f6a7b8c9d0",
  "expires_at": "2026-09-02T10:30:00Z",
  "payload_digest": "sha256:3f2a…",

  "resolved": {
    "model": "siraya/Seedance-2.0-fast", "model_id": "mdl_3h8r5t0v6w", "prompt": "海邊的黃昏，鏡頭緩慢推近",
    "seconds": 5, "resolution": "720p", "aspect_ratio": "16:9",
    "image_url": "https://…/tenants/…/uploads/….jpg",
    "async": true, "seed": null,
    "seed_note": "未指定 seed，上游每次生成的結果都不同；要重現近似結果請指定 seed"
  },
  "materials": [
    { "field": "image_url", "index": 0, "upload_id": "…", "bytes": 545459,
      "mime": "image/jpeg", "sha256": "…",
      "url": "https://…/tenants/…/uploads/….jpg", "preview_url": "https://…" }
  ],
  "estimate": { "output_tokens": 108900, "points": 0.539055,
                "basis": "exact", "billable": { "output_tokens": 108900 },
                "unit": "output_tokens" },
  "balance": { "available": 20.0, "sufficient": true,
               "note": "此報價不保留額度，確認送出時才凍結" }
}

POST /v2/videos/generations

送出一個生成任務。這個呼叫會立即凍結額度，且送出後無法取消。

這條端點有兩種送法，用的是同一個網址、同一份請求欄位，差別只在回應。直接送出是預設：帶齊下表的參數一次送出，回應就是任務本身。先確認再送出則是這一次呼叫帶上 require_confirmation: true（或由帳戶層開啟「送件前確認」）——同樣的請求不會直接送出，平台先把「即將送出的內容」回給你一張確認單（列出即將送出的每一個參數與素材網址、預估點數），你核對無誤再回一個 confirm，才真的送出。像匯款——按下送出之後才跳確認，而不是要你先去別的地方領一張單子再回來。不帶 require_confirmation（或帶 false）、帳戶也沒開，就是直接送出。帳戶層的開關是下限：後台為你的帳戶開啟「送件前確認」之後，即使這一次帶 require_confirmation: false，一樣會回確認單。

請求欄位

回應：直接送出

{
  "object": "video",
  "id": "job_1a2b3c4d5e6f7a8b9c0d",
  "status": "processing",
  "model": "siraya/Seedance-2.0-fast",
  "model_id": "mdl_3h8r5t0v6w",
  "created_at": 1756300000,
  "price_reserved": 0.539055
}

回應中可能出現其他透傳欄位，但只有 id、status、model、price_reserved 是穩定契約，請勿依賴其餘欄位。

回應：先確認再送出時的確認單

開啟送件前確認之後，你照常送出請求——欄位一個都不用改：

curl https://appletoken.app/v2/videos/generations \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "siraya/Seedance-2.0-fast",
    "prompt": "海邊的黃昏，鏡頭緩慢推近",
    "seconds": 5, "resolution": "720p",
    "image_url": "data:image/jpeg;base64,…"
  }'

回應不是任務，而是一張待確認的單子：

{
  "object": "video.confirmation",
  "status": "needs_confirmation",

  "quote_id": "q_a1b2c3d4e5f6a7b8c9d0",
  "expires_at": "2026-09-02T10:30:00Z",
  "payload_digest": "sha256:3f2a…",

  "resolved": {
    "model": "siraya/Seedance-2.0-fast", "model_id": "mdl_3h8r5t0v6w", "prompt": "海邊的黃昏，鏡頭緩慢推近",
    "seconds": 5, "resolution": "720p", "aspect_ratio": "16:9",
    "image_url": "https://…/tenants/…/uploads/….jpg",
    "async": true, "seed": null,
    "seed_note": "未指定 seed，上游每次生成的結果都不同；要重現近似結果請指定 seed"
  },
  "materials": [
    { "field": "image_url", "index": 0, "upload_id": "…", "bytes": 545459,
      "mime": "image/jpeg", "sha256": "…",
      "url": "https://…/tenants/…/uploads/….jpg", "preview_url": "https://…" }
  ],
  "estimate": { "output_tokens": 108900, "points": 0.539055, "basis": "exact" },
  "balance": { "available": 20.0, "sufficient": true,
               "note": "此報價不保留額度，確認送出時才凍結" },

  "next": {
    "confirm": { "method": "POST", "url": "/v2/videos/generations",
                 "body": { "quote_id": "q_a1b2c3d4e5f6a7b8c9d0", "confirm": true } },
    "cancel":  { "method": "POST", "url": "/v2/videos/generations",
                 "body": { "quote_id": "q_a1b2c3d4e5f6a7b8c9d0", "confirm": false } }
  },
  "message": "這是即將送出的內容，目前尚未送出、尚未扣點。…"
}

確認、取消，或再看一次

# 確認送出
-d '{"quote_id": "q_a1b2c3d4e5f6a7b8c9d0", "confirm": true}'

# 取消（要改內容就取消掉，重新送一次完整請求）
-d '{"quote_id": "q_a1b2c3d4e5f6a7b8c9d0", "confirm": false}'

# 只帶 quote_id：把確認內容再看一次，不會送出
-d '{"quote_id": "q_a1b2c3d4e5f6a7b8c9d0"}'

confirm 收布林值，也收人會直接打出來的字："yes"／"y"／"confirm"／"ok" 都算確認，"no"／"cancel" 算取消。填了看不懂的值一律回 400——確認這件事上，猜你的意思是危險的。

確認成功後的回應與一般送件完全相同（多一個 quote_id 欄位），拿 id 去輪詢即可。取消則回 {"object":"video.confirmation","status":"cancelled"}。

確認階段的規則

• 帶了 quote_id 就不能再帶生成參數，否則回 400。要改內容請先取消，再重新送出一次完整請求——確認階段允許改動的話，「確認」就沒有意義了。
• 確認單有效期 15 分鐘，過期回 400。
• 確認之前不凍結額度，確認送出的當下才凍結。
• 兩步必須用同一把憑證；別把憑證（即使是同一個帳戶）一律回 404。
• 同一張確認單重複確認只會產生一個任務，回應帶 "idempotent": true。逾時重試不會扣兩次錢。
• 送件失敗（後端拒收）時額度原路退回，確認單也會退回可用狀態，可以直接重試同一張。
• 素材不會重新上傳——送出去的就是你確認時看到的那幾個檔案。
• 已經送出的取消不了（回 409）：後端沒有取消機制，送出去就收不回來。
• 重複取消不算錯誤，第二次的 cancelled 會是 false，照實告訴你這次沒有真的改變什麼。

同時開多張報價單

同一把憑證可以同時持有多張未確認的報價單，彼此完全獨立，不會互相覆蓋或取消。要對多個模型比價、或一次排好幾支影片再逐一確認，直接開多張就好。

• 每張報價單有自己的 quote_id，確認時各自帶各自的那一張——平台不會替你猜是哪一張。
• 有效期是各自的 15 分鐘，從各自建立的時間起算。
• 報價單不凍結額度，所以多張的總額可以超過你的餘額。超額不會在報價時被擋下來，而是在確認送出的當下才有人撞到 402。
• 撞到 402 的那一張會退回可用狀態，加值後拿同一張 quote_id 直接重試即可；其他還沒確認的報價單不受影響。

做法見完整範例裡的「多張報價單 → 逐一確認送出」。

錯誤

直接送件時，驗證依下列順序進行，先觸發者先回：

1. 缺 model → 400
2. 模型不在憑證的允許清單 → 404
3. 長度或解析度不符模型限制、參考素材數量超過上限、缺必要計價參數 → 400（多個問題會用「；」串接在同一則訊息）
4. 估價金額超過可用餘額 → 402，附 needed 與 available
5. 缺 prompt → 400（刻意排在凍結之前，避免建立又立刻退還的無謂凍結）
6. 凍結額度（此後才會產生費用紀錄）
7. 送往後端；任何階段失敗都會退還凍結，帳本記 release（submit_failed）

帶 quote_id 的確認呼叫走的是另一組檢查：

收到 402 時確認單會退回可用狀態：額度沒有被凍結，這張單子也沒有作廢。加值之後拿同一張 quote_id 再送一次確認即可，不必重新報價（只要還在 15 分鐘有效期內）。

GET /v2/videos/{job_id}

查詢任務狀態。若任務已經完成或失敗，這個呼叫會順手完成結算或退還——但結算不依賴你的查詢：平台的背景程序會做同一件事，兩者走同一段程式碼且彼此冪等，先到者生效。

回應

{
  "object": "video",
  "id": "job_1a2b3c4d5e6f7a8b9c0d",
  "status": "completed",
  "model": "siraya/Seedance-2.0-fast",
  "model_id": "mdl_3h8r5t0v6w",
  "seconds": 5,
  "resolution": "720p",
  "created_at": 1756300000,
  "completed_at": 1756300182,
  "content": "/v2/videos/job_1a2b3c4d5e6f7a8b9c0d/content",
  "outputs": [
    { "type": "original",  "status": "completed",
      "content": "/v2/videos/job_1a2b3c4d5e6f7a8b9c0d/content?output=original" },
    { "type": "processed", "id": "pp_9f8e7d6c5b4a3210fedc", "status": "completed",
      "audio_style": "phone", "intensity": 3,
      "content": "/v2/videos/job_1a2b3c4d5e6f7a8b9c0d/content?output=processed" }
  ],
  "price_charged": 0.539055
}

失敗時的回應長這樣——注意 HTTP 狀態碼仍然是 200，任務失敗不是 HTTP 錯誤，請以 status 欄位判斷，不要只看狀態碼：

{
  "object": "video",
  "id": "job_1a2b3c4d5e6f7a8b9c0d",
  "status": "failed",
  "model": "siraya/Seedance-2.0-fast",
  "model_id": "mdl_3h8r5t0v6w",
  "created_at": 1756300000,
  "completed_at": 1756300182,
  "price_reserved": 1.096198,
  "error": {
    "code": "generation_failed",
    "message": "The request failed because the output audio may be related to copyright restrictions. Request id: 021700000000000000000000000000000000ffffc0a800000000",
    "upstream_message": "The request failed because the output audio may be related to copyright restrictions. Request id: 021700000000000000000000000000000000ffffc0a800000000"
  }
}

• content 只在 completed 時出現，是取件用的相對路徑（接在 https://appletoken.app 後面就是完整網址）。回應裡不會有成品的絕對網址——成品由平台代為轉送，原始網址不外流。若你的程式在等一個叫 url 的欄位，請改讀這個欄位，或直接呼叫 GET /v2/videos/{job_id}/content。
• outputs 只在有後處理時才會有第二筆。第一筆永遠是 type: "original"，指向與 content 相同的路徑；第二筆是 type: "processed"，帶自己的 status。後處理失敗不會影響原片：原片照常交付、照常計費，第二筆的 status 會是 failed 並附 error。content 欄位本身的意義與行為完全沒有改變。成品的 bytes、duration_seconds、sample_rate 不在這裡，改由 GET /v2/post-process/{id} 提供。
• price_charged 只在已結算後出現。尚在 processing 時，回應帶的是 price_reserved。
• error 只在 failed 時出現，形狀是 {"code": "...", "message": "..."}，失敗原因來自後端時另外帶 upstream_message（與選擇性的 upstream_code）。code 是穩定的機器可讀識別，請用它來分支；message 是失敗原因，多數情況是後端回的原文（例如內容審查未通過、參數不被接受、你的後端金鑰額度不足）。請把 message 顯示給你的使用者——把它吞掉、只顯示「生成失敗」，使用者就只剩下試誤這一條路可走，而多數失敗原因其實是他自己改個參數或補個額度就能解決的。
• error.upstream_message 是後端回的原文（其中的供應商名稱已替換成 upstream），結尾的 Request id: … 完整保留——向我們查詢某支任務時請一併提供，我們用它向後端對帳。error.upstream_code 只在後端有給錯誤碼時出現。這兩個欄位從 2026-09-24 起失敗的任務才有；平台自己判定的失敗（例如 generation_timeout）沒有這兩個欄位。
• 結算是冪等的——重複呼叫不會重複扣款，你的查詢與背景程序同時發生也不會。
• 查詢別人的任務一律回 404，而不是 403；我們不透露任務是否存在。
• 查詢時若後端暫時不可用，平台會直接回傳目前已知的狀態，而不是讓你的查詢一起失敗。

GET /v2/videos/{job_id}/content

下載成品。回應是 Content-Type: video/mp4 的原始位元組，不是 JSON、也不是轉址。

• 成品由平台代為取回後轉送，原始成品網址不會外流，也無法被第三方直接存取。
• 下載前平台會先向後端刷新這個任務的狀態。若任務此時已經完成，這次呼叫就可能是觸發結算的那一次——結算是冪等的，與背景程序同時發生也只會扣一次款。仍建議先呼叫 GET /v2/videos/{job_id} 確認 completed，再來取件。
• 任務不存在、不屬於你、或尚無可下載內容，一律回 404。
• 影片成品自任務完成（completed）起由平台保存 30 天，期限內可以重複下載。超過 30 天回 410 content_expired，成品無法再取得，只能重新生成；重試不會成功。少數情況平台沒能存到成品、後端也已經沒有時，同樣回 410 content_expired。需要長期保存請自行下載備份。
• 帶 ?output=processed 可取回後處理片；不帶或帶 ?output=original 都是原片（預設行為與過去完全相同）。後處理尚未完成或已失敗時回 404。

curl -f https://appletoken.app/v2/videos/job_1a2b3c4d5e6f7a8b9c0d/content \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -o output.mp4

# 取回後處理片（例如電話音效那一支）
curl -f "https://appletoken.app/v2/videos/job_1a2b3c4d5e6f7a8b9c0d/content?output=processed" \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -o output_phone.mp4

音軌風格後處理

對影片的音軌套用聲音效果，例如讓對白聽起來像從電話裡傳出來。影像不會被重新編碼，只有音軌被處理，所以畫質與原片完全一致。

兩種用法

1. 生成時順帶：在 POST /v2/videos/generations 帶 post_process，任務完成後自動產出第二支成品。
2. 對既有影片加工：用下面的獨立端點，來源可以是平台上已完成的任務、你上傳的素材，或內嵌的 data URI。

請求

{
  "job_id": "job_1a2b3c4d5e6f7a8b9c0d",
  "audio_style": "phone",
  "intensity": 3
}

回應 202

{
  "object": "video.post_process",
  "id": "pp_9f8e7d6c5b4a3210fedc",
  "status": "queued",
  "audio_style": "phone",
  "intensity": 3,
  "created_at": 1756300000
}

GET /v2/post-process/{id} · GET /v2/post-process/{id}/content · GET /v2/post-process

可用的聲音風格

限制與計費

• 來源影片上限 200 MB、10 分鐘，格式 mp4。
• 來源必須屬於你。引用別人的任務或素材一律回 404，我們不透露它是否存在。
• 處理是非同步的，通常數秒完成。用 GET /v2/post-process/{id} 輪詢，或直接看任務的 outputs。
• 目前不收費。帳務路徑仍然完整（會產生一筆金額 0.0 的用量紀錄），日後若開始計費會事先公告。
• 成品保留在平台，可用 /content 取回。

錯誤碼

錯誤只會回 code 與一句固定文案，不會帶內部細節（檔案路徑、堆疊、後端訊息一律不外流）。
download_failed 與 upload_failed 是暫時性的，平台會自動重試，不會出現在最終狀態；重試到時限仍未成功會變成 postprocess_timeout。

POST /v2/images/generations

圖片生成。與影片不同，這是同步端點：一次呼叫就直接拿到圖片，沒有任務 id、沒有輪詢、沒有取件。所有圖片模型共用這一個端點，帶不帶輸入圖都一樣。

請求欄位

其他未列在上表的欄位會被靜默忽略，不會報錯。

{
  "error": {
    "code": "validation_error",
    "message": "Dola-Seedream-5.0-pro 的 size 只接受 1K、2K，或寬×高像素值（總像素需在 921,600 到 4,624,220 之間）"
  }
}

請求範例

curl -X POST https://appletoken.app/v2/images/generations \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "siraya/ByteDance-Seedream-4.5",
    "prompt": "清晨的港口，薄霧，暖色調",
    "n": 2,
    "size": "1024x1024"
  }'

回應

{
  "id": "img_1a2b3c4d5e6f7a8b9c0d",
  "created": 1774794546,
  "model": "siraya/ByteDance-Seedream-4.5",
  "data": [
    { "url": "https://…/tenants/…/images/….png" },
    { "url": "https://…/tenants/…/images/….png" }
  ],
  "price_charged": 0.08
}

形狀與 OpenAI 的圖片端點相容，只多一個 price_charged。

錯誤

素材資產

資產是你存在平台上、可以重複使用的參考素材。它存在的理由只有一個：含人臉的參考素材，後端不接受公開網址——必須先上傳成資產，再用 asset:// 引用。

可以用來做什麼

這三件事都需要人臉，所以都必須走資產。不含人臉的參考素材（風景、物件、色調參考…）照舊用公開網址或內嵌 data URI 即可，不必上傳成資產。

介面與限制

怎麼上傳

三步：上傳 → 等它變成可用 → 在送件時引用。

第一步：上傳

curl https://appletoken.app/v2/assets \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA…",
    "name": "主角臉部參考"
  }'

回應是 202——已收下，但還不能用：

{
  "id": "ast_a1b2c3d4e5f6a7b8c9d0",
  "object": "asset",
  "type": "image",
  "name": "主角臉部參考",
  "status": "processing",
  "bytes": 545459,
  "mime": "image/jpeg",
  "sha256": "3f2a…",
  "reference": "asset://ast_a1b2c3d4e5f6a7b8c9d0",
  "created_at": 1788000000,
  "activated_at": null
}

第二步：等它變成 active

curl https://appletoken.app/v2/assets/ast_a1b2c3d4e5f6a7b8c9d0 \
  -H "Authorization: Bearer $APPLETOKEN_KEY"

後端是非同步處理的，一般在幾秒到十幾秒內完成。建議每 3 秒查一次，直到 status 變成 active。

第三步：在送件時引用

{
  "model": "siraya/Seedance-2.0",
  "prompt": "這個人在海邊散步，黃昏，鏡頭緩慢推近",
  "seconds": 5,
  "resolution": "720p",
  "input_references": [
    { "type": "image", "url": "asset://ast_a1b2c3d4e5f6a7b8c9d0", "role": "reference_image" },
    { "type": "image", "url": "https://your-cdn.com/背景參考.jpg",   "role": "reference_image" }
  ]
}

同一個請求裡可以混用：含人臉的用 asset://，其餘照舊給網址。role 依型別填 reference_image／reference_video／reference_audio。

帶影片參考時 seconds 怎麼填、輸出多長，取決於 reference_mode，見影片參考與長度——這條規則與資產無關。

列出與刪除

列出你的資產，最新的在前。查詢參數：limit（1–100，預設 50）、status（processing／active／failed）、type（image／video／audio）。回應是 {"object":"list","data":[…]}。

永久刪除，回 204。刪掉之後就不能再用於生成，已經送出的任務不受影響。

錯誤

GET /v2/jobs

列出這張憑證送出的影片任務，最新的在前。適合用在你自己的後台列出近期送件，不必逐一保存 job_id。

Query 參數

curl "https://appletoken.app/v2/jobs?limit=20" \
  -H "Authorization: Bearer $APPLETOKEN_KEY"

回應

{
  "object": "list",
  "data": [
    {
      "id": "job_2b3c4d5e6f7a8b9c0d1e",
      "object": "video",
      "model": "siraya/veo-3.1-generate-001",
      "model_id": "mdl_2b6c8g1j4s",
      "status": "processing",
      "created_at": 1756300500,
      "completed_at": null
    },
    {
      "id": "job_1a2b3c4d5e6f7a8b9c0d",
      "object": "video",
      "model": "siraya/Seedance-2.0-fast",
      "model_id": "mdl_3h8r5t0v6w",
      "status": "completed",
      "created_at": 1756300000,
      "completed_at": 1756300182,
      "content": "/v2/videos/job_1a2b3c4d5e6f7a8b9c0d/content"
    }
  ]
}

• model 一律是「上游/模型」，並帶 model_id；與你送件時用哪種寫法無關。見遷移指南。
• 每一筆的形狀與 GET /v2/videos/{job_id} 相同，status 的意義也相同。
• 只會列出這張憑證送出的任務。同帳戶其他憑證的任務不會出現在這裡。
• 這個端點不會觸發結算，也不會即時向後端更新狀態。要拿到權威的狀態與 price_charged，請對單一任務呼叫 GET /v2/videos/{job_id}。

POST /v2/chat/completions

對話生成。與影片不同，這是同步端點：沒有任務 id、沒有輪詢、沒有取件。一次呼叫要嘛拿到完整回應，要嘛拿到一段 SSE 串流。

請求欄位

其他白名單欄位包括 top_p、n、stop、tools、user 等；支援情況依模型而異，平台不保證它們都會生效。

下列參數只對指定模型（上游 siraya）原樣轉送；送到其他模型會被靜默忽略，與過去相同，不會報錯。值不經平台檢查，效果由模型決定，用量以回應的 usage 為準。

{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":512,"reasoning_effort":"low"}

回應（非串流）

{
  "object": "chat.completion",
  "model": "siraya/ByteDance-Seed-1.8",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "向量資料庫把文字…" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 52, "completion_tokens": 180 },
  "price_charged": 0.004284
}

usage.*_details、service_tier、system_fingerprint、prompt_filter_results、content_filter_results、refusal 是上游帶回、平台照轉的欄位：有沒有、長什麼樣由模型決定，平台不保證一定出現，程式請容許它們缺席。

回應有 id（chatcmpl_…，平台自發、與上游無關）與 created（Unix 秒），但對話不是可查詢的任務——這個 id 不能拿去 /v2/videos/{id}。要對帳請用 /v2/usage 裡對應那一列（它的 job_id 就是這個 id）。

回應（串流，stream: true）

回應標頭是 Content-Type: text/event-stream; charset=utf-8，狀態碼永遠是 200。內容為一連串 data: 事件，以空行分隔：

data: {"object":"chat.completion.chunk","model":"siraya/ByteDance-Seed-1.8","choices":[{"index":0,"delta":{"content":"向量"}}]}

data: {"object":"chat.completion.chunk","model":"siraya/ByteDance-Seed-1.8","choices":[{"index":0,"delta":{"content":"資料庫"}}]}

data: {"object":"chat.completion.chunk","model":"siraya/ByteDance-Seed-1.8","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":52,"completion_tokens":180},"price_charged":0.004284}

data: [DONE]

• 內容片段在 choices[0].delta.content。把它們依序串起來就是完整回應。
• 最後一則 chunk 帶 usage 與 price_charged，delta 為空物件、finish_reason 有值。這是刻意的：你不必再查一次就能對帳。
• 串流以 data: [DONE] 結束。收到它就可以關閉連線。
• 沒有其他 SSE 欄位（event:、id:、retry:），也沒有 keep-alive 註解行。

data: {"object":"error","error":{"code":"upstream_error","message":"生成服務回報錯誤"}}

data: [DONE]

在串流開始「之前」發生的錯誤

驗證、額度檢查、模型解析都發生在第一個 chunk 之前，因此這些錯誤走正常的 HTTP 狀態碼與 JSON 錯誤格式：

平台代選：auto/（v2.9）

用法

把 model 寫成 auto/<模型名稱>，例如 auto/qwen3.8-flash-next。模型名稱是 GET /v2/models 裡 ref 斜線後面那一段（同一個模型由幾家上游供應，這段就相同）。目前只支援 POST /v2/chat/completions（含串流）。

{"model":"auto/qwen3.8-flash-next","messages":[{"role":"user","content":"Hello"}],"max_tokens":256}

選擇規則

• 只從目前可用的上游中選：暫停中、最近連續失敗、這次請求無法報價或不支援串流的上游會先排除。
• 售價不高於上游進價的路才會被選。
• 依這次請求的售價由低到高；售價相同時依上游進價，再依上架先後。

自動換家

只有在還沒送出任何內容給你之前才會換家：連線失敗、5xx、429、逾時。非串流在拿到完整回應之前、串流在第一個 chunk 之前。串流一旦開始就不會換家，之後的錯誤照串流錯誤事件處理，不會重複扣款。

回應

• model：照你送的原字串回（auto/qwen3.8-flash-next）。
• route：只有 auto/ 的回應才有，形如 {"provider": "Sailflow", "model": "sailflow/qwen3.8-flash-next"}，是這次實際使用的上游與模型。串流放在最後一則 chunk（與 usage、price_charged 同一塊）。
• usage：不論走哪一家，一律是 prompt_tokens、completion_tokens、total_tokens；有快取或推理用量時另帶 prompt_tokens_details.cached_tokens、completion_tokens_details.reasoning_tokens。
• 帳單與 /v2/usage 記的是實際使用的上游與模型；標頭 X-AppleToken-Route 也是。

錯誤

GET /v2/me

查詢這張憑證的狀態，以及帳戶的額度。適合用在啟動自檢、餘額看板與低餘額告警。

額度是帳戶層級的：同一個帳戶的每一把憑證查到的餘額都相同，任何一把憑證的消費都會反映在這個數字上。

{
  "id": "9f2c81ab",
  "name": "production",
  "status": "active",
  "granted": 100.0,
  "used": 12.482,
  "reserved": 0.539055,
  "available": 86.978945,
  "allowed_models": null,
  "calls": 37,
  "created_at": 1756000000,
  "last_used_at": 1756300000,
  "expires_at": null,
  "expired": false,
  "prefix": "at_live_9f2c81ab_…",
  "display": "at_live_9f2c81ab_••••••••"
}

GET /v2/usage

取得這張憑證的帳務流水，最新的在前。這是你端對帳的權威來源。

用量以憑證為界（哪支鑰匙做了什麼），額度則是帳戶共用的。同帳戶其他憑證的消費不會出現在這裡，但會影響 /v2/me 的餘額。

Query 參數

回應

{
  "object": "list",
  "data": [
    {
      "id": "80421",
      "job_id": "chatcmpl_5e1f0a9c7b3d2e4f6a8b",
      "model": "siraya/ByteDance-Seed-1.8",
      "model_id": "mdl_9p4d2n7e5f",
      "modality": "text",
      "billable": { "input_tokens": 52, "output_tokens": 180 },
      "price": 0.004284,
      "status": "settled",
      "created_at": 1756300400
    },
    {
      "id": "80418",
      "job_id": "job_1a2b3c4d5e6f7a8b9c0d",
      "model": "siraya/Seedance-2.0-fast",
      "model_id": "mdl_3h8r5t0v6w",
      "modality": "video",
      "billable": { "video_seconds": 5 },
      "price": 0.539055,
      "status": "settled",
      "created_at": 1756300182
    }
  ]
}

請求評價

對你自己的一筆請求打 1–5 分。分數會累積成平台對各模型「效果」的評比，讓所有整合者都受益；評分不影響計費，也不會改變任何既有請求的結果。

request_id 是什麼

就是生成回應裡的 id：對話的 chatcmpl_…、圖片的 img_…、影片的 job_…。它同時是 /v2/usage 每一列的 job_id，三種模態走同一條路。

請求

{
  "request_id": "chatcmpl_5e1f0a9c7b3d2e4f6a8b",
  "score": 4,
  "comment": "回答準確，但比上次慢",
  "tags": ["accurate", "slow"]
}

回應 200

{
  "object": "rating",
  "request_id": "chatcmpl_5e1f0a9c7b3d2e4f6a8b",
  "score": 4,
  "comment": "回答準確，但比上次慢",
  "tags": ["accurate", "slow"],
  "created_at": 1758460000,
  "updated_at": 1758460000
}

新建與覆寫都回 200、同一形狀。GET /v2/ratings/{request_id} 回同一形狀；沒評過的請求回 404。時間戳是 Unix 秒。

規則

• 一個請求一票。同一個 request_id 再送一次就是整筆覆寫——score、comment、tags 全部換成新值（沒帶的欄位視為清空），created_at 不變、updated_at 前進。覆寫不會增加樣本數。
• 只能評本帳戶的請求；同帳戶的任何一把憑證都可以評，也可以覆寫彼此的評分。
• 請求結算後 30 天內才能評分（以 /v2/usage 那一列的 created_at 起算）。逾期回 409 conflict，已有的評分照樣讀得到。
• 只有已結算的請求才評得到：還在生成中的影片、以及失敗而全額退還的請求，都沒有 /v2/usage 那一列，會回 404；影片完成後再評即可。
• 影片若同時做了音軌後處理，評分綁的是生成本身，不是後處理。

錯誤

評分按模型（一家上游的一個模型）聚合，聚合結果經 GET /v2/models 每一列的 rating 公開（每個帳戶算一票，需 20 則且至少 3 個帳戶）；這條端點的回應本身不含上游資訊。

額度模型

每張憑證有三個彼此獨立的數字，恆等式永遠成立：

available  =  granted  −  used  −  reserved
   │            │          │         └─ 已預扣、尚未結算的請求金額
   │            │          └─────────── 已結算的實收累計
   │            └────────────────────── 額度上限（由 AppleToken 設定）
   └─────────────────────────────────── 你現在真正能用的錢

為什麼要「預扣」

生成請求一旦送出就無法取消，成本在那一刻就已經產生。因此平台在請求離開之前先凍結預估金額，確保不會出現超支後才發現餘額不足的情況。這也代表：

• 凍結發生在呼叫後端之前。若後端拒絕或連線失敗，凍結會立即全額退還。
• 同時進行多個請求時，每個請求各自持有一筆凍結，reserved 是它們的總和。
• available 不足以支付預扣時，請求會直接被擋下並回 402，不會產生任何費用。
• 影片的預扣金額是估價（可以事先算準）；對話的預扣金額是最壞情況（輸入 token + max_tokens），結算時幾乎一定會退回大部分。

額度耗盡時

{
  "error": {
    "code": "quota_exceeded",
    "message": "額度不足",
    "needed": 1.25,
    "available": 0.42,
    "granted": 100.0,
    "used": 98.33,
    "reserved": 1.25
  }
}

先看 used：如果它接近 granted，就是單純用完了，請加值。

再看 reserved：這是正在進行中的請求總和。平台會主動追蹤每一筆任務並在它結束時結算，所以 reserved 高只代表你同時跑了很多任務，或者某些任務還在生成——它會自己降下來，不需要你做任何事。若要壓低瞬時的 reserved，方向是限制併發數，以及把對話的 max_tokens 設得貼近實際需要。

用量與計價公式

token 制影片模型（output_tokens）

計費量由畫面尺寸與影格數決定，與內容複雜度無關，因此可以在送出前算得完全精確：

frames  =  24 × seconds + 1                    （影格率固定 24，不可調整）
tokens  =  round( 寬 × 高 ÷ 1024 × frames )
price   =  tokens ÷ 1,000,000 × 單價

實例：Seedance-2.0-fast、5 秒、720p、16:9

寬 × 高   =  1280 × 720  =  921,600 px
每格 token =  921,600 ÷ 1024  =  900
frames    =  24 × 5 + 1  =  121
tokens    =  900 × 121  =  108,900
price     =  108,900 ÷ 1,000,000 × 4.95  =  0.539055 USD

畫面尺寸的決定順序是：

1. 有 size → 直接採用其中的寬高。
2. 否則以 resolution 的數字為短邊，再用 aspect_ratio 推出長邊。

秒制影片模型（video_seconds）

price  =  round(seconds) × 單價          （與解析度、比例都無關）

例如 veo-3.1-generate-001 生成 8 秒：8 × 0.90 = 7.20 USD。

對話的預扣與串流計費

對話是唯一「用量到最後才知道」的能力，因此計費分成兩步：先按上限預扣，結束後按實際結算。兩步都用同一條公式。

公式

price  =  輸入 tokens ÷ 1,000,000 × 輸入單價
       +  輸出 tokens ÷ 1,000,000 × 輸出單價

預扣：輸入 tokens = 平台估算的 prompt 長度
      輸出 tokens = 你給的 max_tokens          ← 最壞情況

結算：輸入 tokens = 實際 prompt_tokens
      輸出 tokens = 實際 completion_tokens     ← 通常遠低於 max_tokens

實例：ByteDance-Seed-1.8，max_tokens: 512

單價（取自 GET /v2/models 的 pricing.components）
  輸入  0.375 / 1M tokens
  輸出  3.00  / 1M tokens

預扣（請求開始）
  估算輸入 48 tokens  ×  0.375 ÷ 1,000,000 =  0.000018
  上限輸出 512 tokens ×  3.00  ÷ 1,000,000 =  0.001536
  reserved                                 =  0.001554 USD

結算（請求結束，實際只產生 180 tokens）
  實際輸入 52 tokens  ×  0.375 ÷ 1,000,000 =  0.000020
  實際輸出 180 tokens ×  3.00  ÷ 1,000,000 =  0.000540
  actual                                   =  0.000560 USD
  delta = actual − reserved                =  −0.000994（退回你的餘額）

"pricing": {
  "unit": "output_tokens", "from": 3, "to": 3,
  "components": [
    { "unit": "input_tokens",  "from": 0.375, "to": 0.375 },
    { "unit": "output_tokens", "from": 3,     "to": 3     }
  ]
}

串流有三種結束方式，三種都會結算

這是串流計費最容易出錯的地方，所以平台把三條路徑收斂到同一個結算出口：

串流的閒置逾時

串流沒有整體逾時——長回應本來就會跑很久。但相鄰兩個 chunk 之間有間隔上限，預設 60 秒。後端連著卻不吐字超過這個時間，平台會中止串流，並照「已產生的部分」結算。

這是刻意的：整體逾時會砍掉正常的長回應，而「連著卻不吐字」一定是出事了，必須有上限，否則連線與凍結會一起無限期懸著。你會在串流中看到一個 upstream_error 事件（訊息「生成服務逾時未回應」），接著是 data: [DONE]。

結算、退還與對帳

四種結局

實收金額怎麼決定

• token 制影片：以後端回報的實際 token 用量重算。若後端未回報用量，則以送件時的估價結算。
• 秒制影片：以實際成品秒數重算；沒有回報時採用送件時的 seconds。
• 對話：以實際輸入／輸出 token 重算；後端沒回報用量或中途斷線時，以平台累計的產出量結算。
• 重算的結果就是 /v2/usage 那一列的 price，計費用量在同一列的 billable。它可能略高或略低於送件時的 price_reserved——差額不會另外列成一筆。

對帳建議

1. 你端以 job_id 為主鍵記錄每個影片任務，並保存送件時回傳的 price_reserved；對話則記錄回應中的 price_charged。
2. 定期拉 GET /v2/usage。用 created_at 圈出你要對的時間區間，並記下這一批裡最大的 id——下次只處理 id 比它大的列，就不會重複也不會漏。
3. job_id 是 job_… 的列（影片）直接對回你自己的任務紀錄，核對 price 與你保存的 price_reserved。有差額是正常的：實收以實際用量重算，可能略高或略低。
4. 對話與圖片的列，job_id 就是回應的 id（chatcmpl_…／img_…），用它對回你自己的請求紀錄，核對 price 與回應中的 price_charged。
5. 你送出了、卻在 /v2/usage 找不到對應列的請求，只有兩種可能：還沒結算（仍在進行中）或已全額退還（送件失敗、生成失敗、零產出的串流）。兩者都不需要你做任何事——用 GET /v2/videos/{job_id} 查狀態就能分辨。只有某筆影片任務超過 2 小時仍停在 processing，才是值得回報的異常（正常情況下最晚 2 小時內就會被系統自動判定為失敗並退還）。
6. 核對 Σ price：帳戶下只有這一張憑證時，它應該等於 /v2/me 的 used；有多張憑證時，各憑證的 Σ price 相加才等於 used。

錯誤格式與狀態碼

{
  "error": {
    "code": "validation_error",
    "message": "example-model 的長度需在 4–15 秒之間",
    "param": "seconds",
    "reason": "out_of_range",
    "value": 20,
    "allowed": {"min": 4, "max": 15}
  }
}

/v2 的影片參數 400 validation_error 另外帶下列機器可讀的欄位。code 與 message 與以前完全相同（只新增欄位）；請用新欄位分流，不要解析 message：

該怎麼分支

錯誤碼總表

回呼（Webhook）

影片（POST /v2/videos/generations）與音軌後處理（POST /v2/post-process，或送件時帶 post_process）進入終態時，平台會對你事先登記的網址發一個簽章過的 POST。只有 /v2；舊版 v1 API 不論怎麼帶都不會通知。圖片與對話是同步回應，沒有回呼。

設定：先登記，再帶入

1. 在主控台 Webhook 頁登記網址：只接受 https、443 埠，主機必須解析到公開網路位址；最多 5 個啟用中的網址。第一次登記時會產生簽章 secret，原文只顯示一次。
2. 送件時二選一：
   • 什麼都不帶：通知「預設」網址（第一個登記的網址自動成為預設，可在主控台更換）。客戶端程式完全不用改。
   • 帶 callback_url（必須完全等於已登記的網址）或 callback_endpoint_id（主控台上的 whe_…），指定這一筆要通知哪一個。

不在清單裡、格式不合（http、非 443、內部網段）一律回 400 validation_error，不收件、不預扣。callbackUrl（camelCase）不是平台的欄位，會被丟棄。兩階段確認時，回呼設定可以帶在第一階段（之後確認出來的那支影片會通知）或第二階段。

curl https://appletoken.app/v2/videos/generations \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "siraya/Seedance-2.0-fast", "prompt": "…", "seconds": 5,
       "callback_url": "https://example.com/appletoken/webhook"}'

事件與內容

內容是精簡版：只有平台自己的欄位（id、狀態、時間、error.code、取件路徑）。失敗原因的完整文字、價格與用量請用 GET 查詢。content 是要帶憑證才拿得到的 API 路徑，不是公開下載網址。

POST /appletoken/webhook HTTP/1.1
Content-Type: application/json
User-Agent: AppleToken-Webhooks/1
X-AppleToken-Event-Id: evt_3f9c2a71b0d84e5a6c1f2e90
X-AppleToken-Event-Type: video.completed
X-AppleToken-Signature: t=1791262582,v1=5b1d…e04a

{
  "event_id": "evt_3f9c2a71b0d84e5a6c1f2e90",
  "type": "video.completed",
  "created_at": 1791262582,
  "data": {
    "id": "job_1a2b3c4d5e6f7a8b9c0d",
    "object": "video",
    "status": "completed",
    "completed_at": 1791262579,
    "error": null,
    "content": "/v2/videos/job_1a2b3c4d5e6f7a8b9c0d/content"
  }
}

驗證簽章

X-AppleToken-Signature 的格式是 t=<unix 秒>,v1=<hex>，v1 = HMAC-SHA256(secret, "<t>." + 原始 body)。請用收到的原始位元組計算、用定時比較，並拒絕時間差超過 5 分鐘的通知（防重放）。輪換 secret 後的 24 小時內，標頭會帶兩個 v1（新舊各一），符合任一即可。

import crypto from 'node:crypto';

// rawBody：收到的原始位元組（不要先 JSON.parse 再 stringify）
function verify(rawBody, header, secret) {
  const t = Number(/t=(\d+)/.exec(header)?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return [...header.matchAll(/\bv1=([0-9a-f]{64})/g)].some((m) =>
    crypto.timingSafeEqual(Buffer.from(m[1]), Buffer.from(expected)));
}

import hashlib, hmac, re, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    m = re.search(r't=(\d+)', header)
    if not m or abs(time.time() - int(m.group(1))) > 300:
        return False
    expected = hmac.new(secret.encode(), m.group(1).encode() + b'.' + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(v, expected) for v in re.findall(r'v1=([0-9a-f]{64})', header))

送達、重試與去重

• 你的伺服器在 5 秒內回 2xx 才算送達；其餘狀態碼、逾時、重新導向（不會跟隨）都算失敗。
• 失敗後依序在 1 分、5 分、15 分、30 分、1 小時、2 小時後重試，之後放棄（約 4 小時）。主控台看得到每一筆的結果，可以手動重送。
• 至少送達一次：可能重複，請用 event_id 去重；重送與重試都沿用同一個 event_id。
• 不保證順序：影片與它的後處理是兩個事件，先後不固定；以 created_at 判斷或直接 GET。
• 通知通常在任務終結後數秒內送出。回呼成功與否不影響任務狀態與扣款。
• 成品自完成起保存 30 天，期限內隨時可取件；過期會回 410 content_expired。

完整範例

影片：估價 → 送件 → 取件

以下三個範例做同一件事：估價 → 送件 → 輪詢到結束 → 下載成品。輪詢是為了知道結果並取件；額度的結算由平台在背景完成，不靠這段程式碼。

#!/usr/bin/env python3
"""AppleToken 最小客戶端 — 只用標準庫。"""
import json, os, time, urllib.request, urllib.error

BASE = "https://appletoken.app/v2"
KEY  = os.environ["APPLETOKEN_KEY"]


def call(path, payload=None, raw=False):
    data = json.dumps(payload).encode() if payload is not None else None
    req = urllib.request.Request(BASE + path, data=data,
                                 method="POST" if data else "GET")
    req.add_header("Authorization", "Bearer " + KEY)
    if data:
        req.add_header("Content-Type", "application/json")
    try:
        with urllib.request.urlopen(req, timeout=120) as r:
            return r.read() if raw else json.loads(r.read())
    except urllib.error.HTTPError as e:
        body = e.read().decode("utf-8", "replace")
        try:
            err = json.loads(body)["error"]
        except Exception:
            err = {"code": "http_%d" % e.code, "message": body[:200]}
        raise RuntimeError("%s: %s" % (err.get("code"), err.get("message")))


def generate(prompt, model="siraya/Seedance-2.0-fast", seconds=5, resolution="720p", **extra):
    params = {"model": model, "seconds": seconds, "resolution": resolution, **extra}

    quote = call("/quote", params)
    print("預估費用 %.6f USD，餘額 %.6f" % (quote["price"], quote["available"]))

    job = call("/videos/generations", {**params, "prompt": prompt})
    job_id = job["id"]
    print("已送出 %s，凍結 %.6f" % (job_id, job["price_reserved"]))

    # 輪詢是為了拿到結果與取件；額度另有平台的背景結算保底
    deadline = time.time() + 900
    time.sleep(10)
    while time.time() < deadline:
        st = call("/videos/" + job_id)
        if st["status"] == "completed":
            print("完成，實收 %.6f USD" % st.get("price_charged", 0))
            return job_id
        if st["status"] == "failed":
            raise RuntimeError("生成失敗，額度已全額退還：" + job_id)
        time.sleep(8)
    raise TimeoutError("等待逾時，請保留 job id 稍後續查：" + job_id)


if __name__ == "__main__":
    jid = generate("清晨的漁港，漁船緩緩進港", seconds=5, aspect_ratio="16:9")
    with open("output.mp4", "wb") as f:
        f.write(call("/videos/%s/content" % jid, raw=True))
    print("已存成 output.mp4")

// AppleToken 最小客戶端 — Node 18+ 內建 fetch，無需任何套件。
import { writeFile } from 'node:fs/promises'

const BASE = 'https://appletoken.app/v2'
const KEY  = process.env.APPLETOKEN_KEY

async function call(path, payload, raw = false) {
  const res = await fetch(BASE + path, {
    method: payload ? 'POST' : 'GET',
    headers: {
      Authorization: `Bearer ${KEY}`,
      ...(payload ? { 'Content-Type': 'application/json' } : {}),
    },
    body: payload ? JSON.stringify(payload) : undefined,
  })
  if (!res.ok) {
    const { error } = await res.json().catch(() => ({ error: {} }))
    throw new Error(`${error.code ?? res.status}: ${error.message ?? res.statusText}`)
  }
  return raw ? Buffer.from(await res.arrayBuffer()) : res.json()
}

const sleep = s => new Promise(r => setTimeout(r, s * 1000))

async function generate(prompt, opts = {}) {
  const params = { model: 'siraya/Seedance-2.0-fast', seconds: 5, resolution: '720p', ...opts }

  const quote = await call('/quote', params)
  console.log(`預估費用 ${quote.price} USD，餘額 ${quote.available}`)

  const job = await call('/videos/generations', { ...params, prompt })
  console.log(`已送出 ${job.id}，凍結 ${job.price_reserved}`)

  // 輪詢是為了拿到結果與取件；額度另有平台的背景結算保底
  const deadline = Date.now() + 900_000
  await sleep(10)
  while (Date.now() < deadline) {
    const st = await call(`/videos/${job.id}`)
    if (st.status === 'completed') {
      console.log(`完成，實收 ${st.price_charged} USD`)
      return job.id
    }
    if (st.status === 'failed') throw new Error(`生成失敗，額度已退還：${job.id}`)
    await sleep(8)
  }
  throw new Error(`等待逾時，請保留 job id 稍後續查：${job.id}`)
}

const id = await generate('清晨的漁港，漁船緩緩進港', { aspect_ratio: '16:9' })
await writeFile('output.mp4', await call(`/videos/${id}/content`, undefined, true))
console.log('已存成 output.mp4')

# 1) 估價
curl -s https://appletoken.app/v2/quote \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"siraya/Seedance-2.0-fast","seconds":5,"resolution":"720p"}'

# 2) 送件，取出 job id
JOB=$(curl -s https://appletoken.app/v2/videos/generations \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"siraya/Seedance-2.0-fast","prompt":"清晨的漁港，漁船緩緩進港",
       "seconds":5,"resolution":"720p","generate_audio":true}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["id"])')
echo "job: $JOB"

# 3) 輪詢到終局狀態（為了知道結果，不是為了釋放額度）
while true; do
  ST=$(curl -s "https://appletoken.app/v2/videos/$JOB" \
       -H "Authorization: Bearer $APPLETOKEN_KEY" \
       | python3 -c 'import sys,json; print(json.load(sys.stdin)["status"])')
  echo "status: $ST"
  [ "$ST" = "completed" ] && break
  [ "$ST" = "failed" ] && { echo "生成失敗，額度已退還"; exit 1; }
  sleep 8
done

# 4) 取件
curl -f "https://appletoken.app/v2/videos/$JOB/content" \
  -H "Authorization: Bearer $APPLETOKEN_KEY" -o output.mp4

影片：多張報價單 → 逐一確認送出

同時對幾個模型詢價，再逐一確認送出。重點有三個：每張報價單各自保存自己的 quote_id、確認時各自帶自己的那一張，以及額度到確認的當下才凍結——所以 402 只會出現在確認這一步，而且撞到之後那張報價單仍然可以用。

#!/usr/bin/env python3
"""同時開多張報價單 → 逐一確認送出 — 只用標準庫。"""
import json, os, urllib.request, urllib.error

BASE = "https://appletoken.app/v2"
KEY  = os.environ["APPLETOKEN_KEY"]


def call(path, payload=None):
    """回傳 (狀態碼, 回應內容)；錯誤不丟例外，因為 402 要當成正常分支處理。"""
    data = json.dumps(payload).encode() if payload is not None else None
    req = urllib.request.Request(BASE + path, data=data,
                                 method="POST" if data else "GET")
    req.add_header("Authorization", "Bearer " + KEY)
    if data:
        req.add_header("Content-Type", "application/json")
    try:
        with urllib.request.urlopen(req, timeout=120) as r:
            return r.status, json.loads(r.read())
    except urllib.error.HTTPError as e:
        body = e.read().decode("utf-8", "replace")
        try:
            return e.code, json.loads(body)
        except Exception:
            return e.code, {"error": {"code": "http_%d" % e.code, "message": body[:200]}}


PROMPT = "清晨的漁港，漁船緩緩進港"
CANDIDATES = [
    {"model": "siraya/Seedance-2.0-fast", "seconds": 5, "resolution": "720p"},
    {"model": "siraya/Seedance-2.0",      "seconds": 5, "resolution": "1080p"},
]

# 1) 一次開多張報價單。彼此獨立，不會互相覆蓋；這一步不凍結任何額度。
slips = []
for params in CANDIDATES:
    status, body = call("/quote", dict(params, prompt=PROMPT))
    if status != 200:
        print("報價失敗 %s：%s" % (params["model"], body["error"]["message"]))
        continue
    slips.append({"model": params["model"],
                  "quote_id": body["quote_id"],      # 各自保存，確認時要帶對的那一張
                  "price": body["price"],
                  "expires_at": body["expires_at"]})  # 各自 15 分鐘
    print("%s 報價 %.6f USD，quote_id=%s，有效到 %s"
          % (params["model"], body["price"], body["quote_id"], body["expires_at"]))

# 2) 逐一確認送出。額度到這一刻才凍結，所以 402 只會在這裡出現。
jobs, retryable = [], []
for s in slips:
    status, body = call("/videos/generations",
                        {"quote_id": s["quote_id"], "confirm": True})
    if status == 200:
        jobs.append(body["id"])
        print("已送出 %s → %s（凍結 %.6f）"
              % (s["model"], body["id"], body["price_reserved"]))
        continue

    err = body["error"]
    if status == 402:
        # 餘額不足：額度沒被凍結，這張報價單退回可用狀態。
        # 加值後拿同一個 quote_id 再確認一次即可，不必重新報價。
        retryable.append(s)
        print("%s 餘額不足（需要 %s，可用 %s）；quote_id 仍可用：%s"
              % (s["model"], err.get("needed"), err.get("available"), s["quote_id"]))
    elif status == 400:
        # 逾期或已取消：這張不能再用了，要重新報價
        print("%s 這張報價單不能用了：%s" % (s["model"], err["message"]))
    else:
        # 上游拒收等其他失敗：凍結已原路退回，報價單也退回可用狀態，可重試同一張
        retryable.append(s)
        print("%s 送出失敗（%s）：%s；稍後可重試同一張"
              % (s["model"], err["code"], err["message"]))

print("已送出 %d 支，還有 %d 張報價單可以重試" % (len(jobs), len(retryable)))
# 之後對每個 job id 輪詢 GET /v2/videos/{id}，做法與上一個範例相同

// 同時開多張報價單 → 逐一確認送出。Node 18+ 內建 fetch，無需任何套件。
const BASE = 'https://appletoken.app/v2'
const KEY  = process.env.APPLETOKEN_KEY

// 回傳 { status, body }；錯誤不丟例外，因為 402 要當成正常分支處理。
async function call(path, payload) {
  const res = await fetch(BASE + path, {
    method: payload ? 'POST' : 'GET',
    headers: {
      Authorization: `Bearer ${KEY}`,
      ...(payload ? { 'Content-Type': 'application/json' } : {}),
    },
    body: payload ? JSON.stringify(payload) : undefined,
  })
  return { status: res.status, body: await res.json() }
}

const PROMPT = '清晨的漁港，漁船緩緩進港'
const CANDIDATES = [
  { model: 'siraya/Seedance-2.0-fast', seconds: 5, resolution: '720p' },
  { model: 'siraya/Seedance-2.0',      seconds: 5, resolution: '1080p' },
]

// 1) 一次開多張報價單。彼此獨立，不會互相覆蓋；這一步不凍結任何額度。
const slips = []
for (const params of CANDIDATES) {
  const { status, body } = await call('/quote', { ...params, prompt: PROMPT })
  if (status !== 200) {
    console.log(`報價失敗 ${params.model}：${body.error.message}`)
    continue
  }
  // 各自保存自己的 quote_id 與到期時間，確認時要帶對的那一張
  slips.push({ model: params.model, quoteId: body.quote_id,
               price: body.price, expiresAt: body.expires_at })
  console.log(`${params.model} 報價 ${body.price} USD，quote_id=${body.quote_id}，有效到 ${body.expires_at}`)
}

// 2) 逐一確認送出。額度到這一刻才凍結，所以 402 只會在這裡出現。
const jobs = []
const retryable = []
for (const s of slips) {
  const { status, body } = await call('/videos/generations',
                                      { quote_id: s.quoteId, confirm: true })
  if (status === 200) {
    jobs.push(body.id)
    console.log(`已送出 ${s.model} → ${body.id}（凍結 ${body.price_reserved}）`)
    continue
  }

  const err = body.error
  if (status === 402) {
    // 餘額不足：額度沒被凍結，這張報價單退回可用狀態。
    // 加值後拿同一個 quote_id 再確認一次即可，不必重新報價。
    retryable.push(s)
    console.log(`${s.model} 餘額不足（需要 ${err.price}，可用 ${err.available}）；quote_id 仍可用：${s.quoteId}`)
  } else if (status === 400) {
    // 逾期或已取消：這張不能再用了，要重新報價
    console.log(`${s.model} 這張報價單不能用了：${err.message}`)
  } else {
    // 上游拒收等其他失敗：凍結已原路退回，報價單也退回可用狀態，可重試同一張
    retryable.push(s)
    console.log(`${s.model} 送出失敗（${err.code}）：${err.message}；稍後可重試同一張`)
  }
}

console.log(`已送出 ${jobs.length} 支，還有 ${retryable.length} 張報價單可以重試`)
// 之後對每個 job id 輪詢 GET /v2/videos/{id}，做法與上一個範例相同

對話：串流讀取

重點只有兩個：每則事件都要檢查 object（錯誤不走狀態碼），以及從最後一則 chunk 取出 price_charged。

#!/usr/bin/env python3
"""AppleToken 對話串流 — 只用標準庫。"""
import json, os, urllib.request

BASE = "https://appletoken.app/v2"
KEY  = os.environ["APPLETOKEN_KEY"]


def chat_stream(messages, model="siraya/ByteDance-Seed-1.8", max_tokens=512):
    body = json.dumps({
        "model": model, "messages": messages,
        "max_tokens": max_tokens, "stream": True,
    }).encode()
    req = urllib.request.Request(BASE + "/chat/completions", data=body, method="POST")
    req.add_header("Authorization", "Bearer " + KEY)
    req.add_header("Content-Type", "application/json")

    charged = None
    with urllib.request.urlopen(req, timeout=300) as r:
        for raw in r:                      # SSE 一行一行讀
            line = raw.decode("utf-8").strip()
            if not line.startswith("data: "):
                continue
            payload = line[6:]
            if payload == "[DONE]":
                break
            ev = json.loads(payload)
            # 一定要檢查 object：串流開始後錯誤不走 HTTP 狀態碼
            if ev.get("object") == "error":
                raise RuntimeError("%s: %s" % (ev["error"]["code"], ev["error"]["message"]))
            delta = ev["choices"][0]["delta"].get("content")
            if delta:
                print(delta, end="", flush=True)
            if "price_charged" in ev:
                charged = ev["price_charged"]
    print()
    return charged


if __name__ == "__main__":
    cost = chat_stream([{"role": "user", "content": "用三句話說明什麼是向量資料庫"}])
    print("實收 %.6f USD" % cost)

// AppleToken 對話串流 — Node 18+ 內建 fetch，無需任何套件。
const BASE = 'https://appletoken.app/v2'
const KEY  = process.env.APPLETOKEN_KEY

async function chatStream(messages, opts = {}) {
  const res = await fetch(`${BASE}/chat/completions`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ model: 'siraya/ByteDance-Seed-1.8', max_tokens: 512, ...opts, messages, stream: true }),
  })
  // 串流「開始之前」的錯誤仍然是正常的 HTTP 狀態碼加 JSON
  if (!res.ok) {
    const { error } = await res.json().catch(() => ({ error: {} }))
    throw new Error(`${error.code ?? res.status}: ${error.message ?? res.statusText}`)
  }

  const reader = res.body.getReader()
  const decoder = new TextDecoder()
  let buffer = ''
  let charged = null

  for (;;) {
    const { value, done } = await reader.read()
    if (done) break
    buffer += decoder.decode(value, { stream: true })

    // SSE 事件可能被切在任何位置，只處理已經看到換行的完整行
    let nl
    while ((nl = buffer.indexOf('\n')) >= 0) {
      const line = buffer.slice(0, nl).trim()
      buffer = buffer.slice(nl + 1)
      if (!line.startsWith('data: ')) continue
      const payload = line.slice(6)
      if (payload === '[DONE]') return charged
      const ev = JSON.parse(payload)
      // 一定要檢查 object：串流開始後錯誤不走 HTTP 狀態碼
      if (ev.object === 'error') throw new Error(`${ev.error.code}: ${ev.error.message}`)
      const delta = ev.choices[0].delta.content
      if (delta) process.stdout.write(delta)
      if (ev.price_charged !== undefined) charged = ev.price_charged
    }
  }
  return charged
}

const cost = await chatStream([{ role: 'user', content: '用三句話說明什麼是向量資料庫' }])
console.log(`\n實收 ${cost} USD`)

# 串流：-N 關掉緩衝，才看得到逐段輸出
curl -N https://appletoken.app/v2/chat/completions \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"siraya/ByteDance-Seed-1.8","max_tokens":512,"stream":true,
       "messages":[{"role":"user","content":"用三句話說明什麼是向量資料庫"}]}'

# 非串流：一次拿完整回應，price_charged 就在裡面
curl -s https://appletoken.app/v2/chat/completions \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"siraya/ByteDance-Seed-1.8","max_tokens":256,
       "messages":[{"role":"user","content":"用一句話說明什麼是向量資料庫"}]}'

上線檢查清單

正確性

• ☐ 憑證存在環境變數或密鑰服務，不在版控、不在前端。
• ☐ 每個送出的 job_id 都持久化，程式重啟後仍會被查詢完並取件（成品保留時間有限）。
• ☐ 輪詢會走到 completed 或 failed 才停，逾時的任務會被排入稍後續查。
• ☐ 送件前呼叫 /v2/quote，把預估費用顯示給使用者或記入你的成本帳。
• ☐ seconds 確定是數字而不是字串（表單取值最容易在這裡出錯）。
• ☐ aspect_ratio 只使用文件列出的六個值。
• ☐ 以 /v2/models 的 modality 分類模型，不要靠 id 前綴猜。

對話

• ☐ 每個對話請求都帶 max_tokens，而且貼近實際需要——它決定預扣金額。
• ☐ 串流讀取器檢查每則事件的 object，遇到 "error" 當成失敗處理。
• ☐ 從最後一則 chunk（或非串流回應）取出 price_charged 記入成本帳。
• ☐ 明白中途斷線仍會為已產生的內容付費，不要用「使用者按停止」當成本控制手段。
• ☐ HTTP 客戶端沒有在串流上套整體逾時（長回應是正常的）。

韌性

• ☐ 429、502、503、504 走指數退避重試；400、401、403 一律不重試。
• ☐ HTTP 逾時設定足夠寬鬆（非串流建議 120 秒），但輪詢間隔不小於 3 秒。
• ☐ 送件的重試有冪等保護——重送等於再付一次錢，請確認上一次真的沒成立。
• ☐ 下載成品後立刻存入你自己的儲存空間，不要依賴平台長期保存。

成本控制

• ☐ 定期呼叫 /v2/me，在 available 低於門檻時告警。
• ☐ 限制併發數：reserved 是所有進行中請求的凍結總和，衝太高會讓後續請求撞到 402。
• ☐ 以 /v2/usage 的 id 為主鍵做每日對帳（有 job_id 的列再對回你的任務紀錄），並用 modality 拆分不同類型的成本。
• ☐ 正式與測試環境使用不同憑證，方便分開看用量、獨立停用。

常見問題

可以取消已送出的任務嗎？

不行。成本在送出當下就已產生，因此沒有取消端點。請在送件前用 /v2/quote 確認參數與費用。對話串流可以中止讀取，但已產生的部分照樣計費。

有 webhook 或回呼通知嗎？

有，只限 /v2：在主控台的 Webhook 頁登記網址後，影片與後處理完成或失敗時平台會主動通知，見回呼（Webhook）。舊版 v1 API 沒有回呼，請求中的 callbackUrl 類欄位會被丟棄。回呼只是提醒，取件仍以輪詢或 GET 為準。另外要澄清一個常見誤解：輪詢不是結算的前提。平台有背景程序負責結算與退還，你不查詢也不會有額度卡住。

生成失敗要付錢嗎？

影片任務失敗時凍結全額退還，used 不受影響；退還由平台自動完成，不需要你輪詢到 failed。

對話則要看有沒有產出：一個 token 都沒產出才全額退還；只要吐出了內容（即使只有半句話、即使後來斷線），那部分照實計費。

為什麼對話一定要給 max_tokens？

因為額度必須在呼叫後端之前凍結，而對話的用量到最後一刻才知道。max_tokens 是「這次最多產出多少」的上限，平台用它算出最壞情況的價格先凍結起來。結算一律以實際用量重算，差額當場退回，所以你付的永遠是實際用量。詳見對話的預扣與串流計費。

串流到一半我把連線關掉，會被收多少？

收「已經產生的部分」。不會整筆退還，也不會照 max_tokens 的預扣全收。差額在斷線的當下就結算完畢。要少花錢，正確作法是把 max_tokens 設小。

對話可以先估價嗎？

/v2/quote 只支援影片模型。對話的費用取決於實際產生多少 token，事前無法算準——但預扣公式是公開的，你可以自己算出「這次最多會花多少」，那正是平台凍結的金額。

可以同時送多個任務嗎？

可以，只要 available 足以覆蓋所有請求的預扣總和。每個請求各持有一筆獨立凍結。建議自行限制併發數，並對 429 做退避。

為什麼 calls 的數字比我的呼叫次數少？

calls 只計算成功建立凍結的請求——影片送件與對話請求都算，估價、查詢、下載、/v2/me 都不算。

用的是哪一家上游的模型？

就是你在 model 裡指定的那一家。v2.0 起上游是公開的：model 寫「上游/模型」（例如 siraya/Seedance-2.0-fast），或寫那個模型的 ID／slug；GET /v2/models 每一列都有 provider 與 upstream_model。平台不會替你換家——換一家上游就是換一個模型，售價與指標也各自不同，要換請自己改 model（見遷移指南）。模型的 ID、slug 與「上游/模型」永久不變；模型下架後會從 /v2/models 消失，呼叫它回 404。

價格會變嗎？

可能會。請從 /v2/models 讀取價格而非寫死，並以 /v2/quote 作為每次影片交易的報價依據。價格調整會事先通知，且既有的請求一律以送出當下生效的費率結算。

有速率限制嗎？

有。平台以 1 分鐘為時間窗做限流：帶 Authorization 標頭的請求是每分鐘 600 次，以憑證分別計數；未帶憑證的請求是每分鐘 20 次，以來源 IP 計數。/healthz 不受限。超過時回 429，error.code 是 rate_limited，訊息是「請求太頻繁，請稍後再試」，不會帶 retry_after。平台保留調整配額的權利，請不要把這些數字寫死進你的整合裡，該做的指數退避照樣要做。

429 有兩種來源，請用 error.code 分辨：rate_limited 是上面說的平台限流；upstream_error 則是上游服務的節流被原樣透傳。兩者的回應都不會帶 retry_after，額度也都不會被扣——請用自己的指數退避重試。

要留意的是整合寫錯造成的失控迴圈——那種情況下額度會在幾秒內燒光，而通常要等到帳單才會發現。請自行限制併發與重試次數。/v2/* 的每一個端點都需要憑證，GET /v2/models 也不例外。

額度不足不會回 429，而是回 402 quota_exceeded，並附上這次需要的金額與當下的可用餘額。那不是節流，重試也不會變好——請先加值，或降低同時進行的請求數。

版本紀錄