Lewati ke konten
SeedAudio

DOKUMENTASI PENGEMBANG

Dokumentasi API Audio

Buat tugas, kueri statusnya, lalu unduh melalui titik akhir situs yang diautentikasi. Simpan kunci API di server Anda.

Diperlukan paket kredit berbayar atau langganan berbayar aktif; kredit yang diberikan saja tidak dapat membuka kunci API. Respons 503 berarti layanan tidak diaktifkan atau tidak tersedia untuk sementara.

1. Mulai cepat

Jalankan contoh ini di terminal server. Python memerlukan permintaan instalasi pip; JavaScript menggunakan Node.js 22 atau lebih baru.

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. Titik akhir dan identitas

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

Semua titik akhir memerlukan Otorisasi: Pembawa. Tugas adalah milik akun tersebut dan dapat diakses menggunakan kunci aktif lain dari akun tersebut. URL unduhan stabil tetapi bersifat pribadi. Jangan pernah memasukkan kunci ke dalam URL. Riwayat masuk menggunakan autentikasi sesi.

3. Parameter permintaan

Tipe Konten: application/json; maksimum 32 KiB. Bidang yang tidak diketahui ditolak. URL referensi harus menggunakan HTTPS publik, bukan alamat internal.

ParameterNilai-nilaiCatatan
modelseed-audio-1.0Model default dan satu-satunya.
promptstringDiperlukan: 1–2048 karakter Unicode, bukan hanya spasi; jeda baris dipertahankan.
audio_referencesstring[]Hingga 3 URL audio HTTPS publik, direferensikan secara berurutan sebagai @Audio1/2/3. Setiap referensi: maksimal 10 MB dan 30 detik, diperiksa oleh layanan pembuatan.
voicestringPrasetel tercantum di bawah; menggunakan satu slot referensi audio.
image_urlstringSatu URL gambar HTTPS publik; tidak dapat digabungkan dengan referensi suara atau audio.
output_formatmp3 / wav / pcm / ogg_opusmp3 bawaan. PCM adalah file mentah dan tidak dapat diputar di browser.
sample_rate8000 / 16000 / 24000 / 32000 / 44100 / 48000Standarnya 24000Hz.
speed / volume0.5–2Keduanya default ke 1; angka terbatas saja.
pitch-12–12bilangan bulat; bawaan 0.
multilingualbooleanBawaan salah; ekstensi API yang tidak mengikuti bahasa halaman.
ID suara yang didukung

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. Status penagihan dan tugas

Pada kredit 75 per menit, tagihan dibulatkan per detik, dengan minimum kredit 10 dan batas kredit 150. Cadangan penciptaan 150; keberhasilan mengembalikan selisih dan kegagalan mengembalikan reservasi. Tanggal kedaluwarsa kredit asli tetap tidak berubah.

8/30/60/120 detik masing-masing berharga 10/38/75/150 kredit. Pembelian yang dananya dikembalikan atau disengketakan tidak lagi memberi akses ke tugas API baru. Untuk langganan, ini berlaku pada pembayaran periode berjalan hingga periode berikutnya dibayar. Pembelian berbayar lainnya tetap memberi akses.

queued → processing → succeeded / failed

berhasil berarti penyimpanan pribadi dan penagihan telah selesai. Pemulihan berlangsung hingga 60 menit; kegagalan pengiriman atau durasi yang dapat diandalkan mengembalikan kredit yang dipesan. Kesalahan hanya berisi informasi yang ada di situs.

Contoh respons yang berhasil

{
  "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. Percobaan ulang dan batasan

Kunci Idempotensi diperlukan: 1–128 huruf, angka atau ._:-. Gunakan kunci baru untuk setiap tugas baru dan pertahankan kunci dan isi saat mencoba ulang. Kunci bersifat unik dalam akun dan versi API selama masa pakai data. Kunci dan isi yang sama mengembalikan tugas awal; isi yang diubah akan menghasilkan 409. Batas waktu tidak berarti pembuatan gagal: jangan coba lagi dengan kunci baru.

Per akun: 6 permintaan pembuatan per menit, 60 menggabungkan kueri dan unduhan per menit, dan tugas 2 dalam penerbangan. Semua kunci memiliki batasan ini. Kapasitas situs juga dapat menghasilkan 429. Jajak pendapat setiap 5 detik.

6. Kesalahan dan pengunduhan

HTTPcodeTindakan
400invalid_requestKunci idempotensi tidak ada, masukan tidak valid, atau kolom tidak diketahui.
401invalid_api_keyKunci hilang, tidak valid, atau dicabut.
402insufficient_creditsKurang dari 150 kredit yang tersedia.
403purchase_requiredTidak ada paket kredit berbayar atau langganan berbayar aktif yang memberi akses, misalnya karena pembayarannya dikembalikan atau disengketakan.
404not_foundTidak ditemukan atau tidak dimiliki oleh akun ini.
409idempotency_conflict / not_readyKunci yang sama dengan input berbeda, atau audio belum siap.
413request_too_largeJSON melebihi 32 KiB.
416RangeRentang byte tidak valid; beberapa rentang tidak didukung.
429rate_limit / concurrency_limitTunggu Retry-After sebelum mencoba lagi.
503api_unavailable / temporarily_unavailableLayanan dinonaktifkan, konfigurasi tidak lengkap atau tidak tersedia untuk sementara. Simpan id tugas dan kunci idempotensi.

Unduhan mendukung rentang byte tunggal, rentang akhiran, dan HEAD. Tanggapan tidak di-cache atau dialihkan ke media eksternal. Contohnya menggunakan MP3; gunakan ekstensi yang sesuai untuk format lain. Pembatalan klien dan panggilan balik yang ditentukan pelanggan tidak ditawarkan; permintaan hasil.