OpenAPI 명령

listenhub openapi 네임스페이스의 모든 명령은 OAuth 로그인 대신 API 키로 인증합니다. 환경을 직접 통제할 수 있고 대화형 브라우저 플로우 대신 장기 자격 증명을 쓰고 싶은 서버와 CI에서 사용하세요.

시작하기 전에 키를 사용할 수 있게 만들어 두세요 — LISTENHUB_API_KEY를 설정하거나 listenhub openapi config set-key로 저장하면 됩니다. 자격 증명이 저장되는 위치와 CLI가 이를 해석하는 순서는 인증을 참고하세요.

export LISTENHUB_API_KEY="lh_sk_..."
listenhub openapi speakers list --language en

이 페이지의 공통 규칙

이 네임스페이스의 모든 명령은 아래 동작을 공유합니다.

• 출력. 기본은 사람이 읽는 텍스트입니다. --json / -j는 기계가 읽을 수 있는 JSON을 stdout으로 출력합니다(에러는 stderr로). JSON은 jq로 파이프하세요.
• 비동기 생성. 생성을 시작하는 명령은 작업을 제출한 뒤 종료 상태에 도달할 때까지 폴링하며 스피너를 표시합니다. 폴링 간격은 10초입니다. --no-wait은 ID를 즉시 반환하고 0으로 종료합니다. --timeout <seconds>는 대기 시간의 상한을 정합니다(기본값은 명령마다 다르며, 아래 각 그룹에 적어 두었습니다).
• 종료 코드. 0 성공, 1 에러, 2 인증, 3 타임아웃.
• 크레딧. 생성에는 크레딧이 소비됩니다. 만들기 전에 해당하는 estimate 명령으로 추정하고, listenhub openapi subscription으로 잔액을 확인하세요. 비용이 고정되어 있다고 가정하지 마세요.

config

저장된 API 키를 관리합니다. CLI는 LISTENHUB_API_KEY를 먼저 읽고, 그다음 set-key가 기록한 파일을 읽습니다.

listenhub openapi config set-key
listenhub openapi config show --json

speakers

계정에서 사용할 수 있는 보이스를 나열합니다. ID 열이 곧 생성 명령에 전달하는 speakerId입니다.

listenhub openapi speakers list --language en

Name, ID, Gender, Language 열로 이루어진 표를 출력합니다.

tts, audio-speech, speech

텍스트를 음성으로 바꾸는 세 가지 방법입니다. 앞의 둘은 바이너리 오디오를 파일로 스트리밍하고, 세 번째는 호스팅된 오디오 URL을 반환합니다.

tts와 audio-speech는 다음 옵션을 공유합니다.

speech 옵션:

# Stream an MP3 to disk
listenhub openapi tts \
  --text "Welcome to ListenHub." \
  --voice <speaker-id> \
  --output welcome.mp3

# Get a hosted audio URL instead
listenhub openapi speech --script "Welcome to ListenHub." --speaker-id <speaker-id>

flow-speech

Flow Speech는 소스나 스크립트를 내레이션 에피소드로 만듭니다. 생성 명령은 processStatus가 success가 될 때까지 폴링하며, --timeout 기본값은 300초입니다.

flow-speech create 옵션:

--source-url 또는 --source-text 중 최소 하나는 필요합니다.

flow-speech tts 옵션:

스크립트와 스피커는 순서대로 짝지어집니다. 첫 번째 --script는 첫 번째 --speaker-id를 쓰는 식이며, 스크립트가 스피커보다 많으면 첫 번째 스피커를 다시 사용합니다.

flow-speech text-stream <episodeId>에는 --event <event>가 필요하며, 값은 script 또는 outline입니다. 원시 SSE 스트림을 stdout으로 씁니다.

# From a source URL, two voices
listenhub openapi flow-speech create \
  --source-url "https://example.com/article" \
  --speaker-id <host-id> \
  --speaker-id <guest-id>

# Directly from scripts
listenhub openapi flow-speech tts \
  --script "Hello and welcome." --speaker-id <host-id> \
  --script "Glad to be here." --speaker-id <guest-id> \
  --title "Episode 1"

listenhub-voice

listenhub-voice-1.0을 사용한 엔드투엔드 오디오 생성 — 일반 내레이션, 음향 효과, 단일 보이스 음성, 다중 화자 대화, 보이스 클로닝, 이미지-투-오디오를 지원합니다. generate는 작업을 만든 뒤 status가 success가 될 때까지 폴링하고(--timeout 기본값 300초), task와 tasks는 기존 작업을 조회합니다.

listenhub-voice generate 옵션:

listenhub-voice tasks 옵션: --page <n>(기본값 1), --page-size <n>(기본값 20, 최대 100), --status <status>(pending, generating, uploading, success, failed 중 하나), --keyword <text>, --json.

listenhub-voice task <taskId>는 --wait(종료 상태까지 폴링), --timeout <seconds>(300), --json을 받습니다.

# Single built-in voice
listenhub openapi listenhub-voice generate \
  --text "Welcome to ListenHub. Here is your daily briefing." \
  --voice "speaker:zh_female_warm" \
  --duration-hint 20

# Two-voice dialogue (@音频N assigns lines in order)
listenhub openapi listenhub-voice generate \
  --text "@音频1 Hi there! @音频2 Hello, how can I help?" \
  --voice "reference:https://example.com/host.mp3" \
  --voice "speaker:zh_male_calm"

# Image to audio
listenhub openapi listenhub-voice generate \
  --text "Describe this scene as a short narrated clip." \
  --image-url "https://example.com/scene.jpg"

voice-clone

참조 오디오로 보이스를 복제하고, 그렇게 만들어진 비공개 보이스를 관리합니다. create는 로컬 오디오 파일 1–6개를 업로드하고 복제가 끝날 때까지 폴링합니다. confirm은 완료된 작업을 재사용 가능한 보이스로 확정하며, 그 스피커 ID는 tts, speech, audio-speech에서 그대로 쓸 수 있습니다. 업로드 방식만 지원하며, 대화형 녹음 플로우는 웹 앱에 있습니다.

복제에는 복제 대상 본인의 동의가 필요합니다. --consent는 그 동의를 확보했다는 선언이며, 이 플래그가 없으면 API가 생성 요청을 거부합니다. 확정은 요금제의 기간별 쿼터 안에서는 무료이고, 쿼터를 넘기면 확정 1회당 300 크레딧이 들며 --use-credits를 전달했을 때만 진행됩니다.

voice-clone create 옵션:

voice-clone confirm은 --task-id <id>, --name <name>, --gender <gender>를 받고 --use-credits는 선택입니다. voice-clone update <speakerId>는 --name과 --gender 중 최소 하나를 받습니다.

폴링은 세 가지 상태 중 하나로 끝납니다. 복제 실패(에러 코드와 메시지), 복제됐지만 미확정(미리듣기 URL, auto-confirm이 저장하지 못한 경우 확정 에러 포함), 확정 완료(스피커 ID)입니다.

# Two-step: clone, listen, then confirm
listenhub openapi voice-clone create --file ./reference.mp3 --lang en --consent
listenhub openapi voice-clone confirm \
  --task-id 6915bde9cca4d3c8ecb3eaf5 --name "My API Voice" --gender female

# One-shot: clone and confirm in the same flow
listenhub openapi voice-clone create \
  --file ./part-1.mp3 --file ./part-2.mp3 --lang ja \
  --consent --auto-confirm --name "My API Voice" --gender female --use-credits

# Speak with the cloned voice
listenhub openapi speech --script "Hello from my own voice." \
  --speaker-id voice-clone-6915bde9cca4d3c8ecb3eaf5

# Manage private voices
listenhub openapi voice-clone speakers
listenhub openapi voice-clone delete 6915c0a2cca4d3c8ecb3eb01

podcast

팟캐스트 에피소드를 생성합니다. 텍스트와 오디오를 한 번에 만들 수도 있고, 둘을 나눠서 텍스트 콘텐츠를 먼저 생성해 검토하거나 스트리밍한 뒤 오디오를 생성할 수도 있습니다. 생성 명령의 --timeout 기본값은 300초입니다.

podcast create 옵션:

podcast text-content는 동일한 소스·스피커 옵션(--query, --source-url, --source-text, --speaker-id, --mode)과 비동기 플래그를 받습니다. --query, --source-url, --source-text 중 최소 하나는 필요합니다.

podcast text-stream <episodeId>에는 --event <event>가 필요하며, 값은 script 또는 outline입니다.

# One-shot: text + audio
listenhub openapi podcast create \
  --query "AI agent trends in 2026" \
  --speaker-id <host-id> \
  --mode quick

# Two-step: text first, then audio
ID=$(listenhub openapi podcast text-content \
  --query "Weekly recap" --speaker-id <host-id> --no-wait -j | jq -r '.episodeId')
listenhub openapi podcast text-stream "$ID" --event script
listenhub openapi podcast generate-audio "$ID"

storybook

Storybook은 해설(explainer)과 슬라이드 에피소드를 만들며, 선택적으로 비디오까지 생성합니다. 생성은 processStatus가 success가 될 때까지 폴링하며, --timeout 기본값은 300초입니다.

storybook create 옵션:

listenhub openapi storybook create \
  --source-url "https://example.com/explainer" \
  --mode slides --skip-audio

image

프롬프트로 AI 이미지를 생성하며, 참조 이미지를 조건으로 줄 수도 있습니다. --reference는 로컬 파일 경로와 URL을 모두 받습니다. 로컬 파일은 읽어서 인라인으로 전송하고, URL은 참조로 전달합니다.

listenhub openapi image create \
  --provider <provider> \
  --prompt "A neon-lit city skyline at dusk" \
  --ratio 16:9 --size 2K

video

AI 비디오 생성. 이 그룹에는 두 가지 인터페이스가 있습니다. 범용 video 명령(텍스트/이미지/참조 기반)과 video pixverse 하위 명령(PixVerse capability API)입니다. 둘 다 status가 success가 될 때까지 폴링하고 --timeout 기본값은 1200초이며, 둘 다 24자 16진수 작업 ID를 사용합니다.

video create

프롬프트는 필수이고, 나머지 옵션은 입력 모드를 고릅니다. 프레임 모드(--first-frame / --last-frame)와 참조 모드(--reference-image / --reference-video / --reference-audio)는 함께 쓸 수 없습니다.

# Text to video
listenhub openapi video create \
  --prompt "A timelapse of clouds over a mountain range" \
  --model doubao-seedance-2-pro \
  --resolution 1080p --duration 8

# First/last frame interpolation
listenhub openapi video create \
  --prompt "Smooth morph between the two frames" \
  --first-frame "https://example.com/a.jpg" \
  --last-frame "https://example.com/b.jpg"

video list와 estimate

video list 옵션: --page <n>(기본값 1), --page-size <n>(기본값 20), --status <status>(pending, generating, uploading, success, failed 중 하나), --json.

video estimate는 --model, --resolution, --duration이 필요하고, --ratio, --has-video-input, --input-video-duration(--has-video-input을 설정한 경우 필수)을 받습니다.

listenhub openapi video estimate \
  --model doubao-seedance-2-pro --resolution 1080p --duration 8

video pixverse

PixVerse는 원자적인 생성 capability와 마케팅 에이전트를 제공합니다. --capability로 하나를 고르세요.

공통 enum:

• 모델(--model): pixverse, v6, v5, v4.5(기본값 pixverse).
• 언어 / 리전(--language): zh, en(기본값 en).
• 품질(--quality): 360p, 540p, 720p, 1080p(기본값 720p).
• 화면 비율(--aspect-ratio): 9:16, 16:9, 1:1, 4:3, 3:4(기본값 16:9).
• 에이전트 타입(--agent-type, --capability agent와 함께): ad_master, promo_mix.

video pixverse generate 옵션:

에셋 플래그는 끝에 초 단위 :duration을 선택적으로 받습니다. 예를 들면 https://example.com/clip.mp4:5입니다. 맨 뒤의 :<integer>만 길이로 해석하므로, 콜론이 들어간 URL도 안전합니다.

# Lip-sync from TTS
listenhub openapi video pixverse generate \
  --capability lip_sync \
  --video "https://example.com/face.mp4" \
  --lip-sync-tts \
  --lip-sync-speaker-id <speaker-id> \
  --lip-sync-content "Hi, here's our product update."

# Marketing agent
listenhub openapi video pixverse generate \
  --capability agent \
  --agent-type ad_master \
  --prompt "30-second ad for a noise-cancelling headset" \
  --image "https://example.com/product.jpg"

video pixverse estimate는 --capability(필수)와 함께 --model, --language, --quality, --duration, --agent-type을 받습니다.

listenhub openapi video pixverse estimate \
  --capability text_to_video --quality 1080p --duration 5

music

Mureka 기반 AI 음악 생성. 비동기 명령(generate, remix, instrumental, soundtrack, track)은 status가 success가 될 때까지 폴링하며 --timeout 기본값은 600초입니다. 분석 명령(recognize, describe, stem)은 동기로 실행됩니다.

생성 명령들에서 공통으로 쓰는 모델 값: auto, mureka-7.6, mureka-8, mureka-9, mureka-o2.

music generate 옵션:

music remix [audio]는 오디오를 위치 인자 파일로 받거나 --audio-url <url> 또는 --provider-song-id <id>로 받으며, 셋 중 정확히 하나만 지정해야 합니다. --lyrics와 --prompt가 필요합니다.

music instrumental은 --prompt와 --reference-audio <file>(mp3/m4a, 최대 10MB) 중 정확히 하나가 필요하며, --model을 받습니다.

music soundtrack은 --image <file>와 --video <file> 중 정확히 하나가 필요하며, --prompt와 --model을 받습니다.

music track [audio]는 오디오를 위치 인자 파일이나 --provider-song-id <id>로 받습니다(정확히 하나). --generate-type(Vocals, Instrumental, Drums, Bass, Guitar, …)과 --prompt가 필요하고, --generate-type이 Vocals이면 --lyrics도 필요합니다. 선택 옵션은 --vocal-gender <male|female>, --generate-start <seconds>, --generate-end <seconds>입니다.

music recognize, music describe, music stem은 각각 --audio <file>(mp3/m4a, 최대 10MB)이 필요합니다. music stem은 --model(audio-separation-1 또는 audio-separation-2)도 받습니다.

music list 옵션: --page <n>(기본값 1), --page-size <n>(기본값 20), --status <status>(pending, generating, uploading, success, failed), --json.

# Generate from a prompt
listenhub openapi music generate \
  --prompt "Upbeat synthwave with a driving bassline" --title "Night Drive"

# Separate an mp3 into stems
listenhub openapi music stem --audio track.mp3

content

URL에서 읽을 수 있는 콘텐츠를 추출하고, 원하면 요약합니다. 비동기이며 status가 completed가 될 때까지 폴링하고 --timeout 기본값은 300초입니다.

content extract 옵션:

listenhub openapi content extract --url "https://example.com/article" --summarize

subscription

구독 요금제와 크레딧 잔액을 표시합니다 — 사용 가능한 총 크레딧, 월 할당량의 사용량/총량, 영구 크레딧, 요금제 이름, 만료일.

listenhub openapi subscription --json

다음 단계