Pular para o conteúdo
SeedAudio

DOCUMENTAÇÃO DO DESENVOLVEDOR

Documentação da API de áudio

Crie uma tarefa, consulte seu status e faça download por meio de um endpoint de site autenticado. Mantenha as chaves de API em seu servidor.

É necessário um pacote de créditos pago ou uma assinatura paga ativa; os créditos de presente por si só não desbloqueiam a API. Uma resposta 503 significa que o serviço não está ativado ou está temporariamente indisponível.

1. Início rápido

Execute estes exemplos em um terminal de servidor. Python requer solicitações de instalação de pip; JavaScript usa Node.js 22 ou 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. Pontos finais e identidade

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 os endpoints requerem Autorização: Portador. As tarefas pertencem à conta e podem ser acessadas usando outra chave ativa dessa conta. Os URLs de download são estáveis, mas privados. Nunca coloque chaves em um URL. O histórico de login usa autenticação de sessão.

3. Parâmetros de solicitação

Tipo de conteúdo: aplicativo/json; máximo 32 KiB. Campos desconhecidos são rejeitados. Os URLs de referência devem usar HTTPS público, não endereços internos.

ParâmetroValoresNotas
modelseed-audio-1.0Modelo padrão e único.
promptstringObrigatório: 1–2048 caracteres Unicode, não apenas espaços em branco; as quebras de linha são preservadas.
audio_referencesstring[]Até três URLs de áudio HTTPS públicos, referenciados em ordem como @Audio1/2/3. Cada referência: no máximo 10 MB e 30 segundos, verificada pelo serviço geração.
voicestringUma predefinição listada abaixo; consome um slot de referência de áudio.
image_urlstringUm URL de imagem HTTPS público; não pode ser combinado com referências de voz ou áudio.
output_formatmp3 / wav / pcm / ogg_opusMP3 padrão. PCM é um arquivo bruto e pode não ser reproduzido em um navegador.
sample_rate8000 / 16000 / 24000 / 32000 / 44100 / 48000Padrão 24.000 Hz.
speed / volume0.5–2Ambos são padronizados como 1; apenas números finitos.
pitch-12–12Inteiro; padrão 0.
multilingualbooleanPadrão falso; uma extensão de API que não segue o idioma da página.
IDs de voz compatíveis

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. Faturamento e status da tarefa

Com créditos 75 por minuto, as cobranças são arredondadas por segundo, com um mínimo de crédito 10 e um limite de crédito 150. Reservas de criação 150; o sucesso retorna a diferença e o fracasso retorna a reserva. As datas de vencimento do crédito original permanecem inalteradas.

8/30/60/120 segundos custam 10/38/75/150 créditos respectivamente. Uma compra reembolsada ou em disputa deixa de desbloquear novas tarefas da API. Em uma assinatura, isso vale para o pagamento do período atual e dura até o pagamento do próximo período. As demais compras pagas continuam liberando o acesso.

queued → processing → succeeded / failed

bem-sucedido significa que o armazenamento privado e o faturamento foram concluídos. A recuperação dura até 60 minutos; falha na entrega ou duração confiável retorna os créditos reservados. Os erros contêm apenas informações do site.

Exemplo de resposta bem-sucedida

{
  "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. Novas tentativas e limites

A chave de idempotência é necessária: 1–128 letras, dígitos ou ._:-. Use uma nova chave para cada nova tarefa e preserve a chave e o corpo ao tentar novamente. As chaves são exclusivas em uma conta e versão da API durante o tempo de vida do registro. A mesma chave e corpo retornam a tarefa original; um corpo alterado retorna 409. Um tempo limite não significa falha na criação: não tente novamente com uma nova chave.

Por conta: solicitações de criação 6 por minuto, consultas e downloads combinados 60 por minuto e tarefas 2 em andamento. Todas as chaves compartilham esses limites. A capacidade do site também pode retornar 429. Pesquisa a cada 5 segundos.

6. Erros e download

HTTPcodeAção
400invalid_requestChave de idempotência ausente, entrada inválida ou campos desconhecidos.
401invalid_api_keyChave ausente, inválida ou revogada.
402insufficient_creditsMenos de 150 créditos disponíveis.
403purchase_requiredNenhum pacote de créditos pago ou assinatura paga ativa desbloqueia o acesso, por exemplo porque o pagamento foi reembolsado ou está em disputa.
404not_foundNão encontrado ou não pertencente a esta conta.
409idempotency_conflict / not_readyMesma tecla com entrada diferente ou áudio não pronto.
413request_too_largeJSON excede 32 KiB.
416RangeIntervalo de bytes inválido; vários intervalos não são suportados.
429rate_limit / concurrency_limitAguarde Retry-After antes de tentar novamente.
503api_unavailable / temporarily_unavailableServiço desativado, configuração incompleta ou temporariamente indisponível. Mantenha o ID da tarefa e a chave de idempotência.

Os downloads suportam um único intervalo de bytes, intervalos de sufixos e HEAD. As respostas não são armazenadas em cache nem redirecionadas para mídia externa. Os exemplos usam MP3; use a extensão apropriada para outros formatos. O cancelamento do cliente e os retornos de chamada definidos pelo cliente não são oferecidos; consulta de resultados.