跳到正文
SeedAudio

DEVELOPER DOCUMENTATION

音訊 API 存取文檔

建立任務、查詢狀態,再從本站鑑權下載。請在伺服器使用密鑰。

需要實付購買過積分包或持有當期付費訂閱;贈送積分本身不解鎖API。請求返回503時,表示服務尚未開放或暫時無法使用。

1. 快速存取

以下命令在服務端終端機執行。首次安裝Python範例依賴:pip install requests;JavaScript範例使用Node.js 22或更新版本。

cURL

export SEEDAUDIO_ORIGIN='https://seedaudio.now'
export SEEDAUDIO_API_KEY='YOUR_API_KEY'

curl --fail-with-body "$SEEDAUDIO_ORIGIN/api/v1/audio/generations" \
  -H "Authorization: Bearer $SEEDAUDIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: rain-scene-001' \
  -d '{"model":"seed-audio-1.0","prompt":"Gentle rain against a window.","output_format":"mp3"}'

# Replace TASK_ID with the returned id. Poll every 5 seconds until terminal.
curl --fail-with-body "$SEEDAUDIO_ORIGIN/api/v1/audio/generations/TASK_ID" \
  -H "Authorization: Bearer $SEEDAUDIO_API_KEY"

# After status is succeeded, download using the same account's active key.
curl --fail-with-body "$SEEDAUDIO_ORIGIN/api/v1/audio/generations/TASK_ID/content" \
  -H "Authorization: Bearer $SEEDAUDIO_API_KEY" -o audio.mp3

JavaScript (Node.js)

const origin = "https://seedaudio.now";
const headers = { Authorization: 'Bearer ' + process.env.SEEDAUDIO_API_KEY };
async function json(response) {
  const data = await response.json();
  if (!response.ok) throw new Error(data.error?.message || 'Request failed');
  return data;
}
// Persist this key with your request; reuse it if the POST response is lost.
const idempotencyKey = 'rain-scene-001';
let task = await json(await fetch(origin + '/api/v1/audio/generations', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
  body: JSON.stringify({ prompt: 'Gentle rain against a window.' })
}));
const deadline = Date.now() + 65 * 60 * 1000;
while (['queued', 'processing'].includes(task.status) && Date.now() < deadline) {
  await new Promise(resolve => setTimeout(resolve, 5000));
  task = await json(await fetch(origin + '/api/v1/audio/generations/' + task.id, { headers }));
}
if (task.status !== 'succeeded') throw new Error(task.error?.message || 'Poll deadline reached; keep the task id.');
const response = await fetch(task.output.url, { headers });
if (!response.ok) throw new Error('Download failed');
const { writeFile } = await import('node:fs/promises');
await writeFile('audio.mp3', new Uint8Array(await response.arrayBuffer()));

Python

import os, time, requests

origin = "https://seedaudio.now"
headers = {"Authorization": "Bearer " + os.environ["SEEDAUDIO_API_KEY"]}
# Keep this key with your request; a new scene needs a new key.
response = requests.post(origin + "/api/v1/audio/generations", timeout=45,
    headers={**headers, "Idempotency-Key": "rain-scene-001"},
    json={"prompt": "Gentle rain against a window."})
response.raise_for_status()
task = response.json()
deadline = time.monotonic() + 65 * 60
while task["status"] in ("queued", "processing") and time.monotonic() < deadline:
    time.sleep(5)
    response = requests.get(origin + "/api/v1/audio/generations/" + task["id"], headers=headers, timeout=90)
    response.raise_for_status()
    task = response.json()
if task["status"] != "succeeded":
    raise RuntimeError(task.get("error") or "Poll deadline reached; keep the task id.")
with requests.get(task["output"]["url"], headers=headers, stream=True, timeout=60) as response:
    response.raise_for_status()
    with open("audio.mp3", "wb") as audio:
        for chunk in response.iter_content(65536):
            audio.write(chunk)

2. 地址與身份

https://seedaudio.now

  • POST /api/v1/audio/generations → 202
  • GET /api/v1/audio/generations/{id} → 200
  • GET / HEAD /api/v1/audio/generations/{id}/content → 200 / 206

三類請求均使用Authorization: Bearer。任務屬於帳戶;可使用該帳戶的其他有效密鑰。下載URL穩定但不公開,不能把金鑰放入URL。登入後的歷史記錄使用會話身分播放。

3. 請求參數

Content-Type: application/json;最大32KiB;未知欄位直接拒絕。只支援公開HTTPS參考位址,不接受內網位址。

參數取值說明
modelseed-audio-1.0預設且唯一模型。
promptstring必填,1–2048個Unicode字符,不能全空白;保留換行。
audio_referencesstring[]最多3個公開HTTPS音訊URL;依序使用@Audio1/2/3。每段最多10MB、30秒,由生成服務校驗。
voicestring使用下方音色ID,佔用1個音訊參考名額。
image_urlstring一個公開HTTPS圖片URL,不能與voice或音訊參考組合。
output_formatmp3 / wav / pcm / ogg_opus預設mp3;PCM為原始文件,不保證瀏覽器可播放。
sample_rate8000 / 16000 / 24000 / 32000 / 44100 / 48000預設24000 Hz。
speed / volume0.5–2預設均為1;必須是有限數。
pitch-12–12整數,預設0。
multilingualboolean預設false;本站擴充參數,不隨頁面語言自動改變。
支援的音色ID

stokie_en · vivi_mixed_en_zh_ja_es_id · mindy_en_es_id_pt_zh · kian_en_zh · cedric_en_zh · sophie_en_zh · jean_en_zh · magnus_en_zh · mabel_en_zh · nadia_en_zh · opal_en_zh · pearl_en_zh · quentin_en_zh · corinne_mixed_en_zh · esther_mixed_en_zh · lyla_mixed_en_zh · tracy_es_zh · sandy_es_mixed_en_zh · felix_zh · celeste_zh · monkey_king_zh

4. 計費與任務狀態

每分鐘75積分,按秒向上取整,每任務最低10、最高150。創建時預留150,成功退差額,失敗全額退回;退款仍保留原批次有效期。

8 / 30 / 60 / 120秒分別收費10 / 38 / 75 / 150積分。被退款或發生爭議的購買不再解鎖新API任務;訂閱以當期付款為準,至下一期付款成功為止。其他有效付費購買不受影響。

queued → processing → succeeded / failed

僅音頻保存和結算都成功後才返回succeeded。最長恢復窗口60分鐘;無法可靠交付或確認時長則失敗退款。 error僅提供本站錯誤訊息。

成功響應範例

{
  "id": "TASK_ID",
  "object": "audio.generation",
  "model": "seed-audio-1.0",
  "status": "succeeded",
  "billing": {
    "reserved_credits": 150,
    "charged_credits": 38,
    "refunded_credits": 112
  },
  "output": {
    "url": "https://seedaudio.now/api/v1/audio/generations/TASK_ID/content",
    "format": "mp3",
    "sample_rate": 24000,
    "duration": 30
  },
  "usage": {
    "audio_seconds": 30
  },
  "error": null
}

5. 重試與限額

Idempotency-Key必填:1–128個英文字母、數字或._:-。每個新任務使用新鍵;同一請求重試保留原鍵和原內容。鍵在同一帳戶和介面版本內唯一,記錄留存期間不得重複使用;同鍵同體返回原任務,同鍵異體409。網路逾時不表示未創建,請勿換鍵盲目重發。

每帳戶每分鐘創建6次,查詢與下載合計60次;最多2個進行中任務。所有密鑰共用限額;全站繁忙也會429。建議每5秒查詢一次。

6. 錯誤與下載

HTTPcode處理
400invalid_request缺少冪等鍵、無效參數或未知欄位。
401invalid_api_key密鑰缺失、無效或已撤銷。
402insufficient_credits不足150可用積分。
403purchase_required沒有可解鎖的實付積分包或當期付費訂閱,例如相關付款已被退款或發生爭議。
404not_found不存在或不屬於目前帳戶。
409idempotency_conflict / not_ready同鍵異體,或文件尚未完成。
413request_too_largeJSON超過32KiB。
416Range下載範圍無效;不支援多段Range。
429rate_limit / concurrency_limit等待Retry-After後重試。
503api_unavailable / temporarily_unavailable服務未啟用、配置未就緒或暫時故障。保留原任務ID和冪等鍵。

下載支援單段Range、後綴Range及HEAD;響應不緩存,也不重定向到外部音源。範例預設MP3,其他格式應使用相符的檔案副檔名。未提供客戶端取消或客戶自訂回調,使用查詢介面取得結果。