Passer au contenu
SeedAudio

DOCUMENTATION DU DÉVELOPPEUR

Documentation de l'API audio

Créez une tâche, interrogez son statut, puis téléchargez-la via un point de terminaison de site authentifié. Conservez les clés API sur votre serveur.

Un pack de crédits payé ou un abonnement payant actif est requis ; les crédits offerts à eux seuls ne débloquent pas l’API. Une réponse 503 signifie que le service n'est pas activé ou est temporairement indisponible.

1. Démarrage rapide

Exécutez ces exemples dans un terminal serveur. Python nécessite des requêtes d'installation pip ; JavaScript utilise Node.js 22 ou version ultérieure.

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. Points de terminaison et identité

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

Tous les points de terminaison nécessitent une autorisation : porteur. Les tâches appartiennent au compte et sont accessibles à l'aide d'une autre clé active de ce compte. Les URL de téléchargement sont stables mais privées. Ne mettez jamais de clés dans une URL. L’historique de connexion utilise l’authentification de session.

3. Paramètres de la demande

Type de contenu : application/json ; maximum 32 Ko. Les champs inconnus sont rejetés. Les URL de référence doivent utiliser le HTTPS public, et non des adresses internes.

ParamètreValeursRemarques
modelseed-audio-1.0Modèle par défaut et unique.
promptstringObligatoire : 1 à 2 048 caractères Unicode, pas uniquement des espaces ; les sauts de ligne sont conservés.
audio_referencesstring[]Jusqu'à 3 URL audio HTTPS publiques, référencées dans l'ordre @Audio1/2/3. Chaque référence : au maximum 10 Mo et 30 secondes, vérifiée par le service génération.
voicestringUn préréglage répertorié ci-dessous ; consomme un emplacement de référence audio.
image_urlstringUne URL d'image HTTPS publique ; ne peut être combiné avec des références vocales ou audio.
output_formatmp3 / wav / pcm / ogg_opusMP3 par défaut. PCM est un fichier brut et ne peut pas être lu dans un navigateur.
sample_rate8000 / 16000 / 24000 / 32000 / 44100 / 48000Par défaut 24 000 Hz.
speed / volume0.5–2Les deux valeurs par défaut sont 1 ; uniquement des nombres finis.
pitch-12–12Entier ; par défaut 0.
multilingualbooleanFaux par défaut ; une extension API qui ne suit pas la langue de la page.
ID vocaux pris en charge

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. Facturation et statut des tâches

Avec des crédits 75 par minute, les frais sont arrondis à la seconde supérieure, avec un minimum de crédit 10 et un plafond de crédit 150. Réserves de création 150 ; le succès renvoie la différence et l'échec renvoie la réservation. Les dates d’expiration initiales du crédit restent inchangées.

8/30/60/120 secondes coûtent respectivement 10/38/75/150 crédits. Un achat remboursé ou contesté ne débloque plus de nouvelles tâches API. Pour un abonnement, cela concerne le paiement de la période en cours et dure jusqu'au paiement de la période suivante. Les autres achats payés continuent de débloquer l'accès.

queued → processing → succeeded / failed

réussi signifie que le stockage privé et la facturation sont terminés. La récupération dure jusqu'à 60 minutes ; un échec de livraison ou de durée fiable restitue les crédits réservés. Les erreurs contiennent uniquement des informations relatives au site.

Exemple de réponse réussie

{
  "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. Nouvelles tentatives et limites

La clé d'idempotence est requise : 1 à 128 lettres, chiffres ou ._:-. Utilisez une nouvelle clé pour chaque nouvelle tâche et conservez la clé et le corps lorsque vous réessayez. Les clés sont uniques au sein d'un compte et d'une version d'API pour la durée de vie de l'enregistrement. La même clé et le même corps renvoient la tâche d'origine ; un corps modifié renvoie 409. Un timeout ne signifie pas que la création a échoué : ne réessayez pas avec une nouvelle clé.

Par compte : requêtes de création 6 par minute, requêtes et téléchargements combinés 60 par minute et tâches 2 en cours. Toutes les clés partagent ces limites. La capacité du site peut également renvoyer 429. Sondage toutes les 5 secondes.

6. Erreurs et téléchargement

HTTPcodeAction
400invalid_requestClé d'idempotence manquante, saisie invalide ou champs inconnus.
401invalid_api_keyClé manquante, invalide ou révoquée.
402insufficient_creditsMoins de 150 crédits disponibles.
403purchase_requiredAucun pack de crédits payé ni abonnement payant actif ne débloque l'accès, par exemple parce que son paiement a été remboursé ou contesté.
404not_foundIntrouvable ou n'appartenant pas à ce compte.
409idempotency_conflict / not_readyMême touche avec une entrée différente ou audio non prêt.
413request_too_largeJSON dépasse 32 Ko.
416RangePlage d'octets non valide ; plusieurs plages ne sont pas prises en charge.
429rate_limit / concurrency_limitAttendez Retry-After avant de réessayer.
503api_unavailable / temporarily_unavailableService désactivé, configuration incomplète ou temporairement indisponible. Conservez l’identifiant de la tâche et la clé d’idempotence.

Les téléchargements prennent en charge une plage d'un seul octet, des plages de suffixes et HEAD. Les réponses ne sont ni mises en cache ni redirigées vers des supports externes. Les exemples utilisent MP3 ; utilisez l'extension appropriée pour les autres formats. L'annulation du client et les rappels définis par le client ne sont pas proposés ; requête pour les résultats.