Saltar al contenido
SeedAudio

DOCUMENTACIÓN DEL DESARROLLADOR

Documentación de la API de audio

Cree una tarea, consulte su estado y luego descárguela a través de un punto final del sitio autenticado. Mantenga las claves API en su servidor.

Se requiere un paquete de créditos pagado o una suscripción de pago activa; Los créditos regalados por sí solos no desbloquean la API. Una respuesta 503 significa que el servicio no está activado o no está disponible temporalmente.

1. Inicio rápido

Ejecute estos ejemplos en una terminal de servidor. Python requiere solicitudes de instalación de pip; JavaScript usa Node.js 22 o posterior.

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. Puntos finales e identidad

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

Todos los puntos finales requieren Autorización: Portador. Las tareas pertenecen a la cuenta y se puede acceder a ellas utilizando otra clave activa de esa cuenta. Las URL de descarga son estables pero privadas. Nunca pongas claves en una URL. El historial de inicios de sesión utiliza la autenticación de sesión.

3. Solicitar parámetros

Tipo de contenido: aplicación/json; máximo 32 KiB. Los campos desconocidos se rechazan. Las URL de referencia deben utilizar HTTPS público, no direcciones internas.

ParámetroValoresNotas
modelseed-audio-1.0Modelo predeterminado y único.
promptstringRequerido: 1–2048 caracteres Unicode, no solo espacios en blanco; Los saltos de línea se conservan.
audio_referencesstring[]Hasta 3 URL de audio HTTPS públicas, referenciadas en orden como @Audio1/2/3. Cada referencia: como máximo 10 MB y 30 segundos, comprobada por el servicio generación.
voicestringUn ajuste preestablecido que se enumera a continuación; consume una ranura de referencia de audio.
image_urlstringUna URL de imagen HTTPS pública; no se puede combinar con referencias de voz o audio.
output_formatmp3 / wav / pcm / ogg_opusMP3 predeterminado. PCM es un archivo sin formato y es posible que no se reproduzca en un navegador.
sample_rate8000 / 16000 / 24000 / 32000 / 44100 / 48000Predeterminado 24000 Hz.
speed / volume0.5–2Ambos tienen el valor predeterminado 1; números finitos únicamente.
pitch-12–12Entero; predeterminado 0.
multilingualbooleanPor defecto es falso; una extensión API que no sigue el idioma de la página.
ID de voz compatibles

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. Estado de facturación y tareas

A los créditos 75 por minuto, los cargos se redondean por segundo, con un mínimo de crédito 10 y un límite de crédito 150. Reservas de creación 150; el éxito devuelve la diferencia y el fracaso devuelve la reserva. Las fechas de vencimiento del crédito original permanecen sin cambios.

8/30/60/120 segundos cuestan 10/38/75/150 créditos respectivamente. Una compra reembolsada o en disputa ya no desbloquea nuevas tareas de API. En una suscripción, esto se aplica al pago del período actual y dura hasta que se pague el siguiente período. Las demás compras pagadas siguen desbloqueando el acceso.

queued → processing → succeeded / failed

tuvo éxito significa que tanto el almacenamiento privado como la facturación están completos. La recuperación dura hasta 60 minutos; la entrega o la falta de duración confiable devuelven los créditos reservados. Los errores contienen solo información orientada al sitio.

Ejemplo de respuesta exitosa

{
  "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. Reintentos y límites

Se requiere clave de idempotencia: 1–128 letras, dígitos o ._:-. Utilice una nueva clave para cada nueva tarea y conserve la clave y el cuerpo cuando vuelva a intentarlo. Las claves son únicas dentro de una cuenta y versión de API durante la vigencia del registro. La misma clave y cuerpo devuelve la tarea original; un cuerpo modificado devuelve 409. Un tiempo de espera no significa que la creación haya fallado: no vuelva a intentarlo con una nueva clave.

Por cuenta: solicitudes de creación 6 por minuto, consultas y descargas combinadas 60 por minuto y tareas 2 en proceso. Todas las claves comparten estos límites. La capacidad del sitio también puede devolver 429. Encuesta cada 5 segundos.

6. Errores y descarga

HTTPcodeacción
400invalid_requestFalta clave de idempotencia, entrada no válida o campos desconocidos.
401invalid_api_keyClave faltante, inválida o revocada.
402insufficient_creditsMenos de 150 créditos disponibles.
403purchase_requiredNingún paquete de créditos pagado ni suscripción de pago activa desbloquea el acceso, por ejemplo porque su pago fue reembolsado o está en disputa.
404not_foundNo encontrado o no es propiedad de esta cuenta.
409idempotency_conflict / not_readyMisma tecla con diferente entrada o audio no listo.
413request_too_largeJSON supera los 32 KiB.
416RangeRango de bytes no válido; No se admiten varios rangos.
429rate_limit / concurrency_limitEspere a Reintentar después antes de volver a intentarlo.
503api_unavailable / temporarily_unavailableServicio deshabilitado, configuración incompleta o no disponible temporalmente. Mantenga la identificación de la tarea y la clave de idempotencia.

Las descargas admiten un rango de un solo byte, rangos de sufijos y HEAD. Las respuestas no se almacenan en caché ni se redirigen a medios externos. Los ejemplos utilizan MP3; utilice la extensión adecuada para otros formatos. No se ofrecen cancelación de clientes ni devoluciones de llamadas definidas por el cliente; consulta de resultados.