生成 API 文件

透過 API 建立生成任務，需要購買過付費積分包或有有效的付費訂閱，而且只扣付費積分。帳號的任何金鑰都能查詢、列出與下載。

快速開始

在 API 金鑰頁建立一把金鑰，只放在你的伺服器上，並設成 API_KEY。下面的範例用 seed-audio-1.0 建立一個生成任務，查詢到它結束，再下載第一個檔案。

每個新請求送出一個新的 Idempotency-Key。請求沒有收到回應時，用同一個鍵和同樣的請求內容再送一次：你拿到的是第一次請求建立的任務，只扣一次費。

export API_ORIGIN='https://demo.freshapp.ai'
export API_KEY='sk_YOUR_API_KEY'

curl --fail-with-body "$API_ORIGIN/api/v1/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1001' \
  -d '{"model":"seed-audio-1.0","input":{"prompt":"黎明時分懸崖上的燈塔，海面平靜，光線柔和。"}}'

# Read it every 5 to 10 seconds until its status ends.
curl --fail-with-body "$API_ORIGIN/api/v1/generations/GENERATION_ID" \
  -H "Authorization: Bearer $API_KEY"

# A delivered output's url is a signed link: no key needed.
curl --fail-with-body -o result "OUTPUT_URL"

import { createClient } from './open-api-client';

const client = createClient({
  baseUrl: "https://demo.freshapp.ai",
  apiKey: process.env.API_KEY, // on your server only
});
const generation = await client.create(
  {
    "model": "seed-audio-1.0",
    "input": {
      "prompt": "黎明時分懸崖上的燈塔，海面平靜，光線柔和。"
    }
  },
  { idempotencyKey: "order-1001" }
);
const done = await client.wait(generation.id);
for (const output of done.outputs)
  if (output.status === 'delivered') {
    const file = await client.download(output);
    // file.body is the output, as output.content_type says
  }

import { createClient } from './open-api-client';
import { useGeneration } from './open-api-react';

// In a browser on this site: no key, the visitor's own session.
const client = createClient();

export function Progress({ id }: { id: string }) {
  const { generation, error, done } = useGeneration(client, id);
  if (error) return <p>{String(error)}</p>;
  return <p>{generation?.status ?? '…'}{done ? ' ✓' : ''}</p>;
}

金鑰與權限

每個請求都在 Authorization: Bearer 中帶上 API 金鑰頁建立的金鑰。金鑰是 sk_ 加上 43 個字母、數字、連字號或底線，只在建立與輪換時顯示一次。帶有 Authorization 的請求只依這把金鑰判斷，不會改用旁邊的登入狀態。

金鑰要嘛只讀（查清單、查任務、下載），要嘛也能生成（建立與取消）。只讀金鑰嘗試建立或取消時會得到 403 insufficient_scope，不會寫入任何資料。

金鑰可以帶一份由位址與網段組成的 IP 白名單：從其他位址送來的請求會得到 403 ip_not_allowed。給金鑰更多權限、調高上限或放寬白名單，需要最近重新登入過；收緊則不需要。

輪換金鑰會立刻產生新值，舊值馬上失效。撤銷金鑰後它永久失效：還沒送交模型的任務會被取消並退回積分，已經在執行的任務照常完成。

只有具付費資格的帳號才能透過 API 建立任務（否則是 403 not_eligible），而且 API 只扣付費積分（不足時是 402 insufficient_credits）。贈送積分與簽到積分只留給網站使用。

生成 API 介面

所有路徑都在本站上。請求與回應的內容都是 JSON，結果檔案除外。

https://demo.freshapp.ai

模型與價格

本站已啟用的模型，依 API 的寫法列出：把編號填入 model，把欄位填入 input。請求在建立時預留它最貴的可能結果，結束後依實際交付的部分收費。

冪等鍵

建立生成任務必須帶 Idempotency-Key 標頭，由 1 到 128 個字母、數字、句點、冒號、底線或連字號組成。建議使用你自己系統裡的編號，例如訂單編號，讓同一件事永遠使用同一個鍵。

同一個鍵加上同樣的請求，不論送幾次都回傳同一個任務，只扣一次費。同一個鍵加上不同的請求會得到 409 idempotency_conflict，不會建立任何任務。

逾時或連線中斷並不代表請求失敗。請用同一個鍵和同樣的請求內容再送一次，並在收到回應前一直保留這兩樣。5xx、429 和 408 也一樣處理：依 Retry-After 等待，然後原封不動再送一次。

狀態與輪詢

用 GET /api/v1/generations/{id} 查詢任務：一開始每 5 秒一次，之後最長每 10 秒一次，直到狀態結束。遇到 429 時，Retry-After 會告訴你何時再查。

billing.reserved_credits 是建立任務時預留的積分。結算後，charged_credits 是實際收取的積分，refunded_credits 是退回的積分；結算前兩者都是 null，held_credits 顯示正在佔用的積分。

等待人工核對的任務會在 review 中顯示核對開始的時間，核對結束前積分一直佔用；核對後任務繼續，或者積分退回。

結果檔案

每個已交付的輸出都有一個本站上的 url。用金鑰查詢時，它是一個簽章連結，一小時內不帶金鑰、從任何位址都能開啟，可以直接交給下載工具。超過一小時後，再查一次任務就能拿到新的連結。

用金鑰本身請求 GET /api/media/{id} 也能取得檔案，但受這把金鑰的白名單限制。兩種方式都支援 HEAD 和一個位元組範圍（Range: bytes=0-1023），而且不會轉址到其他網站。

輸入中引用的檔案（例如一段音訊樣本或一張圖片）必須是這個帳號在網站上上傳的、本站內建的樣本，或來自本站允許來源的連結；其他引用會在預留積分之前就被拒絕。

限額

下面每一項都是本站目前執行的限額，每次拒絕都會說明碰到了哪一項。

• 一次請求最多預留 150 積分，也就是已啟用模型中最貴一次請求的費用。可以替金鑰設得更低，請求中的 max_credits 能為這一次再調低；超過時回傳 400 request_limit_exceeded。
• 每把金鑰每個 UTC 日最多花 5,000 積分，可以自行設定，最高 1,000,000；超過後這把金鑰會得到 429 key_daily_limit_exceeded，直到下一個 UTC 日。
• 一個帳號的所有金鑰加上它授權的 AI 用戶端，每個 UTC 日合計最多花 10,000 積分，可以為帳號另設上限；超過後回傳 429 account_daily_limit_exceeded。
• 每把金鑰與每個帳號每分鐘最多建立與取消 20 次、查詢與下載 240 次；超過後回傳 429 rate_limited，並附上 Retry-After。
• 一個帳號同時執行的生成任務最多 2 個；再建立會得到 429 too_many_active。
• 請求內容最多 32 KiB 的 JSON；更大的回傳 413 request_too_large。

錯誤碼

錯誤的格式是 {"error": {"code": …, "message": …}}。code 一定是下表中的一個，message 是寫給開發者的英文說明。429 和 503 會在 Retry-After 中給出需要等待的秒數。失敗或被取消的任務會在 error 欄位中帶上標示為任務錯誤的碼之一。

TypeScript 用戶端與 React hook

TypeScript 用戶端 open-api-client.ts 不需要任何其他套件，可以在伺服器、Worker 和瀏覽器中執行。在伺服器上傳入 baseUrl 和 apiKey；在本站的瀏覽器頁面中兩者都不傳，請求會使用訪客自己的登入狀態。

create 會送出 Idempotency-Key（你提供的，或新產生的隨機值），遇到連線中斷、5xx、429 或 408 時用同一個請求重送，並依 Retry-After 等待。放棄時，錯誤中帶著這個鍵，你可以稍後用它重送。傳入 store（例如 localStorage）後，重新整理頁面也會沿用第一次的鍵。

wait 會一直查詢任務直到結束：一開始間隔 5 秒，之後最長 10 秒，中止時立刻停下。download 下載一個輸出的檔案，只對本站自己的未簽章連結帶上金鑰。

React hook open-api-react.ts 用用戶端的 wait 追蹤一個任務，元件卸載時停止。下載這兩個檔案，放在同一個目錄中，並把副檔名改成 .ts。

檔案下載