콘텐츠로 건너뛰기
SeedAudio

개발자 문서

오디오 API 문서

작업을 생성하고 해당 상태를 쿼리한 다음 인증된 사이트 엔드포인트를 통해 다운로드하세요. 서버에 API 키를 보관하세요.

유료 크레딧 팩 또는 유효한 유료 구독이 필요합니다. 선물받은 크레딧만으로는 API의 잠금을 해제할 수 없습니다. 503 응답은 서비스가 활성화되지 않았거나 일시적으로 사용할 수 없음을 의미합니다.

1. 빠른 시작

서버 터미널에서 다음 예제를 실행하세요. Python에는 pip 설치 요청이 필요합니다. 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. 엔드포인트 및 ID

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. 요청 매개변수

콘텐츠 유형: 애플리케이션/json; 최대 32KiB. 알 수 없는 필드는 거부됩니다. 참조 URL은 내부 주소가 아닌 공개 HTTPS를 사용해야 합니다.

매개변수가치메모
modelseed-audio-1.0기본이자 유일한 모델입니다.
promptstring필수: 1~2048개의 유니코드 문자(공백만 해당되지 않음) 줄 바꿈이 유지됩니다.
audio_referencesstring[]@Audio1/2/3 순서로 참조되는 최대 3개의 공개 HTTPS 오디오 URL. 각 참조: 최대 10MB, 30초, 생성 서비스에서 확인됩니다.
voicestring아래에 나열된 사전 설정; 하나의 오디오 참조 슬롯을 사용합니다.
image_urlstring공개 HTTPS 이미지 URL 1개 음성 또는 오디오 참조와 결합할 수 없습니다.
output_formatmp3 / wav / pcm / ogg_opus기본 mp3. PCM는 원시 파일이므로 브라우저에서 재생되지 않을 수 있습니다.
sample_rate8000 / 16000 / 24000 / 32000 / 44100 / 48000기본값은 24000Hz입니다.
speed / volume0.5–2둘 다 기본값은 1입니다. 유한한 숫자만.
pitch-12–12정수; 기본값은 0입니다.
multilingualboolean기본 거짓; 페이지 언어를 따르지 않는 API 확장입니다.
지원되는 음성 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

성공은 프라이빗 스토리지와 결제가 모두 완료되었음을 의미합니다. 복구는 최대 60분 동안 지속됩니다. 배송 또는 안정적인 기간 실패로 인해 예약된 크레딧이 반환됩니다. 오류에는 사이트 관련 정보만 포함됩니다.

성공적인 응답 예시

{
  "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. 재시도 및 제한

멱등성 키가 필요합니다: 1~128자 문자, 숫자 또는 ._:-. 새로운 작업마다 새 키를 사용하고 재시도할 때 키와 본문을 보존하세요. 키는 레코드 수명 동안 계정 및 API 버전 내에서 고유합니다. 동일한 키와 본문이 원래 작업을 반환합니다. 변경된 본문은 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잘못된 바이트 범위입니다. 여러 범위는 지원되지 않습니다.
429rate_limit / concurrency_limit재시도하기 전에 Retry-After를 기다리십시오.
503api_unavailable / temporarily_unavailable서비스가 비활성화되었거나 구성이 불완전하거나 일시적으로 사용할 수 없습니다. 작업 ID와 멱등성 키를 유지합니다.

다운로드는 단일 바이트 범위, 접미사 범위 및 HEAD를 지원합니다. 응답은 캐시되거나 외부 미디어로 리디렉션되지 않습니다. 예제에서는 MP3를 사용합니다. 다른 형식에는 적절한 확장자를 사용하세요. 클라이언트 취소 및 고객 정의 콜백은 제공되지 않습니다. 결과를 쿼리합니다.