AppleToken API

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

這個 API 是什麼

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

基底網址

https://appletoken.app

版本前綴

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

協定

HTTPS，HTTP/1.1

認證

Authorization: Bearer at_live_…

編碼

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

金額單位

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

三件事值得先知道

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

五分鐘上手

1. 取得憑證

向 AppleToken 索取一組 API 憑證，格式長這樣：

at_live_9f2c81ab_kJ3nR7xQwZ0pLm5TfYbHs2VdEcAu1NgX

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

2. 看看有哪些模型

取得你這張憑證可以使用的模型與現行價格：

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

3. 先問價格

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

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

4. 送出任務

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

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

5. 輪詢到完成

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

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

6. 取件

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

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

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

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

對話是同步的，沒有任務 id、不需要輪詢：

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

max_tokens 不可省略——平台以它為上限預扣額度。完整契約見 POST /v1/chat/completions。

認證

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

Authorization: Bearer at_live_9f2c81ab_kJ3nR7xQwZ0pLm5TfYbHs2VdEcAu1NgX

憑證結構

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

保管建議

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

憑證失效時的行為

/v1/* 不使用 cookie，因此沒有 CSRF 相關要求；也不綁定來源 IP。

請求與回應慣例

請求

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

錯誤

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

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

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

模型目錄

可用的模型與價格會隨時增減，所以不列在這份文件裡—— 這裡只講不會變的協定規則。你需要知道兩件事：id 是你在請求裡寫的字串， 命名穩定、不會因為底層更換而變動；modality 決定它走哪一組端點—— video 走 /v1/videos/generations， image 走 /v1/images/generations， text 走 /v1/chat/completions， 互相呼叫會得到 400。

兩種計價單位

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

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

多段費率

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

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

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

三種輸入模式

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

參考素材的數量上限

影片參考與長度

當 input_references 含 type: "video" 的項目時，成品長度由參考影片決定，你給的 seconds 不會改變輸出長度。

• seconds 仍然必填——平台用它估價與預扣額度。
• 實際長度與最終費用以結算為準；最終金額就是 /v1/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 秒的硬上限—— 沒有上界的請求會凍結一筆上游必然拒絕的金額。
• 整數為宜。長度只由這個參數決定——在 prompt 裡寫「三十秒的影片」不會生效。

解析度 resolution 與尺寸 size

• resolution 接受 "480p"、"720p"、"1080p" 等形式（也接受不帶 p 的 "720"），必須在該模型的支援清單內。
• size 可直接指定像素，格式 "1280x720"。同時提供時 size 優先決定計價用的畫面尺寸。
• token 制的模型必須至少提供 resolution 或 size 其中之一，否則無法精算用量，會回 400。

畫面比例 aspect_ratio

音訊 generate_audio

• 布林值。僅對音訊欄位標示為 ✅ 的模型有效。
• 模型的 constraints.audio 為 false 時不支援音訊；對它傳 true 不會報錯，但成品不會有聲音。 未宣告 audio 的模型代表平台沒有這項資訊，實際是否出聲以上游行為為準。
• 音訊不影響計價——費用只看畫面尺寸、影格數或秒數。

對話參數

GET /v1/models

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

不帶任何參數時，行為與這個端點原本的樣子完全相同——回傳同一份完整清單，既有整合不需要修改。以下三個查詢參數都是選填，讓你在目錄變大之後可以自行篩選。

Query 參數

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

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

回應

{
  "data": [
    {
      "id": "Seedance-2.0-fast",
      "label": "Video Fast",
      "description": "生成較快，成本較低",
      "modality": "video",
      "constraints": {
        "minSeconds": 4,
        "maxSeconds": 15,
        "resolutions": ["480p", "720p"],
        "audio": true
      },
      "pricing": { "unit": "output_tokens", "from": 4.95, "to": 4.95 }
    },
    {
      "id": "veo-3.1-generate-001",
      "label": "Video Cinema",
      "description": "電影感畫質，固定 4/6/8 秒",
      "modality": "video",
      "constraints": {
        "allowedSeconds": [4, 6, 8],
        "resolutions": ["720p", "1080p"],
        "audio": true
      },
      "pricing": { "unit": "video_seconds", "from": 0.9, "to": 0.9 }
    },
    {
      "id": "ByteDance-Seed-1.8",
      "label": "Chat Pro",
      "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     }
        ]
      }
    }
  ]
}

內嵌檔案自動轉存

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

適用的參數：影片端點（POST /v1/videos/generations）的 image_url、input_references、frame_images——巢狀在物件或陣列裡的值也會被處理；以及圖片端點（POST /v1/images/generations）的 image，那裡只收圖片型別（image/png、image/jpeg、image/webp、image/gif）。對話端點（POST /v1/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。
• 值不是 data URI 時完全不受影響——一般網址原樣送給後端，這個功能不會改變既有整合的行為。

POST /v1/quote

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

請求欄位

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

回應：兩條路徑

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

路徑一：純比價

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

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

{
  "model": "imagen-4-fast",
  "unit": "request",
  "billable": { "request": 2 },
  "price": 0.12,
  "estimated": false,
  "available": 20.0
}

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

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

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

{
  "model": "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": "Seedance-2.0-fast", "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 /v1/videos/generations

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

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

請求欄位

回應：直接送出

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

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

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

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

curl https://appletoken.app/v1/videos/generations \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "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": "Seedance-2.0-fast", "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": "/v1/videos/generations",
                 "body": { "quote_id": "q_a1b2c3d4e5f6a7b8c9d0", "confirm": true } },
    "cancel":  { "method": "POST", "url": "/v1/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 /v1/videos/{job_id}

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

回應

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

• content 只在 completed 時出現，是取件用的相對路徑（接在 https://appletoken.app 後面就是完整網址）。回應裡不會有成品的絕對網址——成品由平台代為轉送，原始網址不外流。若你的程式在等一個叫 url 的欄位，請改讀這個欄位，或直接呼叫 GET /v1/videos/{job_id}/content。
• outputs 只在有後處理時才會有第二筆。第一筆永遠是 type: "original"，指向與 content 相同的路徑；第二筆是 type: "processed"，帶自己的 status。後處理失敗不會影響原片：原片照常交付、照常計費，第二筆的 status 會是 failed 並附 error。content 欄位本身的意義與行為完全沒有改變。成品的 bytes、duration_seconds、sample_rate 不在這裡，改由 GET /v1/post-process/{id} 提供。
• price_charged 只在已結算後出現。尚在 processing 時，回應帶的是 price_reserved。
• 結算是冪等的——重複呼叫不會重複扣款，你的查詢與背景程序同時發生也不會。
• 查詢別人的任務一律回 404，而不是 403；我們不透露任務是否存在。
• 查詢時若後端暫時不可用，平台會直接回傳目前已知的狀態，而不是讓你的查詢一起失敗。

GET /v1/videos/{job_id}/content

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

• 成品由平台代為取回後轉送，原始成品網址不會外流，也無法被第三方直接存取。
• 下載前平台會先向後端刷新這個任務的狀態。若任務此時已經完成，這次呼叫就可能是觸發結算的那一次——結算是冪等的，與背景程序同時發生也只會扣一次款。仍建議先呼叫 GET /v1/videos/{job_id} 確認 completed，再來取件。
• 任務不存在、不屬於你、或尚無可下載內容，一律回 404。
• 成品保留時間有限，請在完成後盡快下載並存到你自己的儲存空間。
• 帶 ?output=processed 可取回後處理片；不帶或帶 ?output=original 都是原片（預設行為與過去完全相同）。後處理尚未完成或已失敗時回 404。

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

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

音軌風格後處理

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

兩種用法

1. 生成時順帶：在 POST /v1/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 /v1/post-process/{id} · GET /v1/post-process/{id}/content · GET /v1/post-process

可用的聲音風格

限制與計費

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

錯誤碼

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

POST /v1/images/generations

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

請求欄位

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

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

請求範例

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

回應

{
  "id": "img_1a2b3c4d5e6f7a8b9c0d",
  "created": 1774794546,
  "model": "imagen-4-fast",
  "data": [
    { "url": "https://…/tenants/…/images/….png" },
    { "url": "https://…/tenants/…/images/….png" }
  ],
  "price_charged": 0.12
}

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

錯誤

素材資產

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

可以用來做什麼

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

介面與限制

怎麼上傳

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

第一步：上傳

curl https://appletoken.app/v1/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/v1/assets/ast_a1b2c3d4e5f6a7b8c9d0 \
  -H "Authorization: Bearer $APPLETOKEN_KEY"

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

第三步：在送件時引用

{
  "model": "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 必須是 -1（長度由輸入影片決定）——這條規則與資產無關，見影片送件。

列出與刪除

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

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

錯誤

GET /v1/jobs

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

Query 參數

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

回應

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

• 每一筆的形狀與 GET /v1/videos/{job_id} 相同，status 的意義也相同。
• 只會列出這張憑證送出的任務。同帳戶其他憑證的任務不會出現在這裡。
• 這個端點不會觸發結算，也不會即時向後端更新狀態。要拿到權威的狀態與 price_charged，請對單一任務呼叫 GET /v1/videos/{job_id}。

POST /v1/chat/completions

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

請求欄位

其他欄位（top_p、n、stop、tools、user 等）目前不被支援，會被靜默忽略。

回應（非串流）

{
  "object": "chat.completion",
  "model": "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
}

回應沒有 id 也沒有 created——對話不是可查詢的任務，沒有識別碼可以拿。要對帳請用 /v1/usage 裡對應那一列的 id（對話的列 job_id 為 null）。

回應（串流，stream: true）

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

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

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

data: {"object":"chat.completion.chunk","model":"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 錯誤格式：

GET /v1/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 /v1/usage

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

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

Query 參數

回應

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

額度模型

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

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 /v1/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 重算；後端沒回報用量或中途斷線時，以平台累計的產出量結算。
• 重算的結果就是 /v1/usage 那一列的 price，計費用量在同一列的 billable。它可能略高或略低於送件時的 price_reserved——差額不會另外列成一筆。

對帳建議

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

錯誤格式與狀態碼

{
  "error": {
    "code": "validation_error",
    "message": "veo-3.1-generate-001 只接受 4/6/8 秒"
  }
}

該怎麼分支

錯誤碼總表

完整範例

影片：估價 → 送件 → 取件

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

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

BASE = "https://appletoken.app/v1"
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="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/v1'
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: '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/v1/quote \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"Seedance-2.0-fast","seconds":5,"resolution":"720p"}'

# 2) 送件，取出 job id
JOB=$(curl -s https://appletoken.app/v1/videos/generations \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"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/v1/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/v1/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/v1"
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": "Seedance-2.0-fast", "seconds": 5, "resolution": "720p"},
    {"model": "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 /v1/videos/{id}，做法與上一個範例相同

// 同時開多張報價單 → 逐一確認送出。Node 18+ 內建 fetch，無需任何套件。
const BASE = 'https://appletoken.app/v1'
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: 'Seedance-2.0-fast', seconds: 5, resolution: '720p' },
  { model: '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 /v1/videos/{id}，做法與上一個範例相同

對話：串流讀取

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

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

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


def chat_stream(messages, model="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/v1'
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: '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/v1/chat/completions \
  -H "Authorization: Bearer $APPLETOKEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"ByteDance-Seed-1.8","max_tokens":512,"stream":true,
       "messages":[{"role":"user","content":"用三句話說明什麼是向量資料庫"}]}'

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

上線檢查清單

正確性

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

對話

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

韌性

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

成本控制

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

常見問題

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

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

有 webhook 或回呼通知嗎？

目前沒有，請求中的 callbackUrl 類欄位會被丟棄，請使用輪詢。但要澄清一個常見誤解：輪詢不是結算的前提。平台有背景程序負責結算與退還，你不查詢也不會有額度卡住。輪詢的目的是知道結果、把成品抓下來。

生成失敗要付錢嗎？

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

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

為什麼對話一定要給 max_tokens？

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

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

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

對話可以先估價嗎？

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

可以同時送多個任務嗎？

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

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

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

底層用的是哪一家的模型？

這是 AppleToken 的實作細節，不對外揭露，也不需要你關心。我們保證的是文件所列的介面、能力與價格；底層供應商更換時，你的整合不需要任何修改。

價格會變嗎？

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

有速率限制嗎？

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

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

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

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

版本紀錄