API

음악 · 효과음 생성 API

효과음은 요청하면 바로 결과를 받을 수 있습니다. 시간이 걸리는 음악은 작업을 등록한 뒤 완료되면 받습니다. 모든 응답에 AI 생성 안내가 포함됩니다.

초안 정식 공개 전 API로, 필드가 추가될 수 있습니다.

시작하기

모든 요청에 Authorization: Bearer <키> 헤더를 넣습니다. API 키는 내 계정 › API 키에서 발급할 수 있으며(프로 등급 이상), 발급 직후 한 번만 표시됩니다. 기본 URL은 https://audiostudio.gensapps.com/v1입니다.

생성 요청은 무료이며, 소리 파일을 처음 받을 때 스튜디오 다운로드와 같은 크레딧이 차감됩니다. 같은 파일을 다시 받을 때는 차감되지 않습니다. 길이, 후보 수, 동시 작업 수는 등급에 따라 다릅니다.

설치 
export AUDIO_STUDIO_KEY="as-..."
pip install httpx
export AUDIO_STUDIO_KEY="as-..."

효과음 · 환경음 POST /v1/sound-effects

한 번에 후보 4개를 생성합니다. wait: true를 넣으면 생성이 끝날 때까지(최대 90초) 기다린 뒤 결과를 바로 반환합니다. 한국어 설명은 영어로 번역해 생성하며, 번역한 문장은 작품 정보에 함께 남습니다.

필드설명기본값
prompt생성할 소리 설명필수
duration_s길이(0.5~30초)5
wait생성이 끝날 때까지 기다린 뒤 결과 받기false
title내 라이브러리에 표시할 제목설명 앞부분
POST /v1/sound-effects 
const res = await fetch("https://audiostudio.gensapps.com/v1/sound-effects", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.AUDIO_STUDIO_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    prompt: "a heavy wooden door slams shut",
    duration_s: 4,
    wait: true,       // 생성이 끝날 때까지 대기(최대 90초), 후보 4개
  }),
});
const { items } = await res.json();   // [{ id, url, seconds, seed }, …]
res = httpx.post(
    "https://audiostudio.gensapps.com/v1/sound-effects",
    headers={"Authorization": f"Bearer {os.environ['AUDIO_STUDIO_KEY']}"},
    json={
        "prompt": "a heavy wooden door slams shut",
        "duration_s": 4,
        "wait": True,  # 생성이 끝날 때까지 대기(최대 90초), 후보 4개
    },
    timeout=120,
)
items = res.json()["items"]  # [{"id", "url", "seconds", "seed"}, …]

음악 · 노래 POST /v1/music

생성 시간이 길어 작업으로 등록되며 202 응답을 반환합니다. 응답의 position(앞에서 대기 중인 작업 수)을 사용자 화면에 그대로 표시하면 됩니다.

필드설명기본값
prompt장르 · 분위기 · 악기 · 보컬필수
lyrics가사. [Verse], [Chorus] 같은 구간 태그를 사용합니다. 노래는 필수—
instrumental연주곡 여부false
duration_s길이(10초 ~ 등급별 최대 길이)60
bpm · key · time_signature빠르기(BPM), 조성(예: A minor), 박자(4 · 3 · 6)자동
n후보 수(등급별 최대치까지)2
seed생성 시드 값무작위
POST /v1/music → GET /v1/jobs/{id} 
const api = "https://audiostudio.gensapps.com";
const headers = { Authorization: `Bearer ${process.env.AUDIO_STUDIO_KEY}`, "Content-Type": "application/json" };

// 1) 작업 요청: 202 응답과 대기 순서를 받는다
const job = await (await fetch(`${api}/v1/music`, {
  method: "POST", headers,
  body: JSON.stringify({
    prompt: "K-pop ballad, soft female vocal, piano, strings",
    lyrics: "[Verse]\n창문 너머 비가 내려와\n…",
    duration_s: 120,
    bpm: 72,
    key: "A minor",
    n: 1,
  }),
})).json();   // { id, status: "queued", position: 0, items: [], ai_notice }

// 2) 완료되면 파일 받기: 처음 받을 때만 크레딧이 차감된다
let done;
do {
  await new Promise((r) => setTimeout(r, 3000));
  done = await (await fetch(`${api}/v1/jobs/${job.id}`, { headers })).json();
} while (done.status !== "succeeded" && done.status !== "failed");
const mp3 = await fetch(api + done.items[0].url, { headers });
console.log(done.ai_notice, mp3.headers.get("X-Credits-Charged"));
api = "https://audiostudio.gensapps.com"
headers = {"Authorization": f"Bearer {os.environ['AUDIO_STUDIO_KEY']}"}

# 1) 작업 요청: 202 응답과 대기 순서를 받는다
job = httpx.post(f"{api}/v1/music", headers=headers, json={
    "prompt": "K-pop ballad, soft female vocal, piano, strings",
    "lyrics": "[Verse]\n창문 너머 비가 내려와\n…",
    "duration_s": 120,
    "bpm": 72,
    "key": "A minor",
    "n": 1,
}).json()   # {"id", "status": "queued", "position": 0, "items": [], "ai_notice"}

# 2) 완료되면 파일 받기: 처음 받을 때만 크레딧이 차감된다
while True:
    time.sleep(3)
    done = httpx.get(f"{api}/v1/jobs/{job['id']}", headers=headers).json()
    if done["status"] in ("succeeded", "failed"):
        break
mp3 = httpx.get(api + done["items"][0]["url"], headers=headers, follow_redirects=True)  # 서명 URL로 302 리디렉션
print(done["ai_notice"], mp3.headers["X-Credits-Charged"])

작업 상태 · 파일 GET /v1/jobs/{id} · GET /v1/works/{id}/audio.mp3

status는 queued → running → succeeded 또는 failed로 바뀝니다. 완료되면 items(후보별 id · url · seconds · seed)와 ai_notice가 함께 반환됩니다. 파일은 같은 API 키로 url에 요청해 받습니다(.wav는 WAV 다운로드를 지원하는 등급만). 응답 헤더 X-Credits-Charged에 차감된 크레딧이 표시됩니다. 파일은 10분 동안 유효한 저장소 주소로 리디렉션(302)되므로, 클라이언트가 리디렉션을 따라가도록 설정해 주세요.

오류

코드의미조치
400입력값 오류(상세 내용은 error.message)입력값을 수정해 다시 요청합니다
401API 키 없음, 잘못된 키 또는 폐기된 키API 키를 확인합니다
403현재 등급에서 사용할 수 없는 기능 또는 형식등급을 확인합니다
402크레딧 부족크레딧을 충전합니다
429동시 작업 수 초과진행 중인 작업이 끝난 뒤 다시 요청합니다