ListenHub Voice

テキスト、参照ボイス、画像から音声や効果音をエンドツーエンドで非同期生成し、タスクをポーリングして完成した音声を取得します。

ListenHub Voice API は音声をエンドツーエンドで生成します — プレーンなナレーション、効果音、単一ボイスの音声、複数話者の対話、参照クリップからのボイスクローン、画像から音声まで対応します。生成は非同期です。リクエストを送信し、完了するまでタスクをポーリングします。すべてのエンドポイントは https://api.marswave.ai/openapi/v1/listenhub-voice 配下にあり、Authorization: Bearer $LISTENHUB_API_KEY で認証します。

ListenHub Voice は現在期間限定で無料です。無料期間の終了後は、追ってお知らせする内容に従って課金が再開されます。

すべてのレスポンスは { "code": 0, "message": "", "data": { ... } } でラップされます。code が 0 以外の場合はエラーです — エラー処理を参照してください。以下の例はいずれも data からフィールドを読み取ります。

モデルと制限

項目	値
`model`	`listenhub-voice-1.0`（デフォルト、かつ唯一のサポート値）
レート制限	ユーザーごとに 1 分あたり 5 リクエスト、`/generate` に適用
`text`	最大 1400 文字
`voices`	1–3 件（プレーンテキスト / 効果音の場合は省略）
`durationHint`	1–110 秒（クレジット見積もり + 目標の長さのヒント）

ボイス（voices）

voices は誰が話すかを決めます。各項目は次の 2 種類のいずれかです。

`type`	必須フィールド	説明
`speaker`	`id`	組み込みボイス — ListenHub のボイスコード、またはプラットフォームの `voice_type`。このタイプでは `url` を送らないでください。
`reference`	`url`	ボイスのクローン元となるカスタム参照音声の URL（http/https）。最長 30 秒、10MB 以下、`wav`/`mp3`/`pcm`/`ogg_opus`。このタイプでは `id` を送らないでください。

複数話者の対話では、2–3 件のボイスを列挙し、text の各行の先頭に @音频1、@音频2… を付けて、順番どおりに台詞をボイスへ割り当てます。voices を完全に省略すると、プレーンなナレーションまたは純粋な効果音を生成します。

voices と image は併用できません — 送れるのはどちらか一方だけです。両方を含むリクエストは拒否されます。speaker 項目は id のみ、reference 項目は url のみを持つ必要があります。混在させると 33004（パラメータ不正）が返ります。

非同期タスクのライフサイクル

POST /v1/listenhub-voice/generate に生成リクエストを送信します。レスポンスには taskId と、初期状態の status（pending）が含まれます。
GET /v1/listenhub-voice/tasks/{taskId} をポーリングします。status は pending → generating → uploading → success と遷移します。
success になったら audioUrl を読み取ります。failed の場合は errorMessage を読み取ります。

ステータス	意味
`pending`	作成済み。生成への送信待ちです。
`generating`	生成中です。`audioUrl` はまだ利用できません。
`uploading`	生成完了。音声をストレージへ転送中です。
`success`	完了。`audioUrl` が利用できます。
`failed`	いずれかの段階で失敗しました。`errorMessage` に理由が入ります。予約済みのクレジットは返還されます。

ListenHub Voice タスクを作成する

POST /v1/listenhub-voice/generate

テキスト（任意でボイスまたは参照画像を添えて）を送信し、エンドツーエンドで音声を生成します。JSON を送信します。202 と taskId を返します。

# Plain text / sound effects (no voices)
curl -X POST "https://api.marswave.ai/openapi/v1/listenhub-voice/generate" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "A gentle rain falls on a quiet street at midnight.",
    "durationHint": 20
  }'

# Single voice (speaker)
curl -X POST "https://api.marswave.ai/openapi/v1/listenhub-voice/generate" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to ListenHub. Here is your daily briefing.",
    "voices": [{ "type": "speaker", "id": "zh_female_warm" }]
  }'

# Voice cloning from a reference clip
curl -X POST "https://api.marswave.ai/openapi/v1/listenhub-voice/generate" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "@音频1 Hi there! @音频2 Hello, how can I help?",
    "voices": [
      { "type": "reference", "url": "https://example.com/host.mp3" },
      { "type": "speaker", "id": "zh_male_calm" }
    ]
  }'

const response = await fetch(
  'https://api.marswave.ai/openapi/v1/listenhub-voice/generate',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text: 'Welcome to ListenHub. Here is your daily briefing.',
      voices: [{ type: 'speaker', id: 'zh_female_warm' }],
      durationHint: 20,
    }),
  },
)
const { data } = await response.json()
console.log('Task ID:', data.taskId)

import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/listenhub-voice/generate',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'text': 'Welcome to ListenHub. Here is your daily briefing.',
        'voices': [{'type': 'speaker', 'id': 'zh_female_warm'}],
        'durationHint': 20,
    },
)
data = response.json()['data']
print('Task ID:', data['taskId'])

画像から音声を生成する場合は、voices の代わりに image オブジェクトを送ります（両者は併用できません）。

{
  "text": "Describe this scene as a short narrated clip.",
  "image": { "url": "https://example.com/scene.jpg" }
}

リクエストパラメータ：

フィールド	型	必須	説明
`model`	string	いいえ	`listenhub-voice-1.0`。デフォルトは `listenhub-voice-1.0`
`text`	string	はい	読み上げるスクリプト。最大 1400 文字。`@音频N` プレフィックスで対話の各行をボイスに割り当てます
`voices`	array	いいえ	1–3 件のボイス項目（ボイスを参照）。プレーンテキスト / 効果音の場合は省略します。`image` とは併用できません
`image`	object	いいえ	画像から音声を生成する際の参照画像。`url`（http/https）と `data`（Base64、`data:image/...;base64,` プレフィックス付きも可）のうち、ちょうど 1 つを指定します。画像は 1 枚、10MB 以下、`jpeg`/`png`/`webp`。`voices` とは併用できません
`audioConfig`	object	いいえ	出力の調整（下記参照）
`durationHint`	number	いいえ	目標の長さ、`1`–`110` 秒。クレジット見積もりを左右し、モデルへのヒントになります
`watermark`	boolean	いいえ	音声ウォーターマークを追加します

audioConfig のフィールド：

フィールド	型	必須	説明
`speechRate`	number	いいえ	話す速さ、`-50`–`100`
`loudnessRate`	number	いいえ	音量、`-50`–`100`
`pitchRate`	number	いいえ	ピッチ、`-12`–`12`
`format`	string	いいえ	`mp3`（デフォルト）、`wav`、`pcm`、`ogg_opus`

202 を返します。

{
  "code": 0,
  "message": "",
  "data": {
    "taskId": "68e780390fc5c9a54f695a7e",
    "status": "pending"
  }
}

単一タスクを照会する

GET /v1/listenhub-voice/tasks/{taskId}

単一のタスクを取得します。生成リクエストを送信したあと、ポーリングに使うエンドポイントです。

curl -X GET "https://api.marswave.ai/openapi/v1/listenhub-voice/tasks/{taskId}" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

const response = await fetch(
  `https://api.marswave.ai/openapi/v1/listenhub-voice/tasks/${taskId}`,
  { headers: { Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}` } },
)
const { data } = await response.json()
console.log('Status:', data.status)
if (data.status === 'success') console.log('Audio:', data.audioUrl)

import os
import requests

response = requests.get(
    f'https://api.marswave.ai/openapi/v1/listenhub-voice/tasks/{task_id}',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
)
data = response.json()['data']
print('Status:', data['status'])
if data['status'] == 'success':
    print('Audio:', data['audioUrl'])

成功したタスクの例：

{
  "code": 0,
  "message": "",
  "data": {
    "id": "68e780390fc5c9a54f695a7e",
    "status": "success",
    "model": "listenhub-voice-1.0",
    "params": {
      "text": "Welcome to ListenHub. Here is your daily briefing.",
      "voices": [{ "type": "speaker", "id": "zh_female_warm" }]
    },
    "audioUrl": "https://assets.listenhub.ai/listenhub-voice/68e780390fc5c9a54f695a7e.mp3",
    "audioDuration": 18.4,
    "creditCharged": 12,
    "creditRefunded": 0,
    "createdAt": 1730000000000,
    "updatedAt": 1730000040000
  }
}

タスクレスポンスのフィールド：

フィールド	型	説明
`id`	string	タスク ID
`status`	string	`pending`、`generating`、`uploading`、`success`、`failed` のいずれか
`model`	string	`listenhub-voice-1.0`
`params`	object	送信したリクエストのエコー（機密の画像 / 音声ペイロードは除去されます。インライン画像は `{ "hasData": true }` として表示され、任意で `thumbnailUrl` が付きます）
`audioUrl`	string	完成した音声の URL。`status` が `success` のときのみ返ります
`audioDuration`	number	音声の長さ（秒。課金対象となる長さ）
`creditCharged`	number	実際に消費されたクレジット（未消費の場合は `0`）
`creditRefunded`	number	失敗時に返還されたクレジット（照合用）
`errorMessage`	string	失敗の理由。`status` が `failed` のときのみ返ります
`createdAt`	number	作成日時（ミリ秒タイムスタンプ）
`updatedAt`	number	最終更新日時（ミリ秒タイムスタンプ）

タスク一覧を取得する

GET /v1/listenhub-voice/tasks

自分の ListenHub Voice タスクを、新しい順に一覧表示します。

curl -X GET "https://api.marswave.ai/openapi/v1/listenhub-voice/tasks?page=1&pageSize=20&status=success" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

const response = await fetch(
  'https://api.marswave.ai/openapi/v1/listenhub-voice/tasks?page=1&pageSize=20',
  { headers: { Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}` } },
)
const { data } = await response.json()
console.log(`${data.total} tasks, showing ${data.items.length}`)

import os
import requests

response = requests.get(
    'https://api.marswave.ai/openapi/v1/listenhub-voice/tasks',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    params={'page': 1, 'pageSize': 20},
)
data = response.json()['data']
print(data['total'], 'tasks, showing', len(data['items']))

クエリパラメータ：

フィールド	型	必須	説明
`page`	integer	いいえ	ページ番号、最小 `1`。デフォルトは `1`
`pageSize`	integer	いいえ	1 ページあたりの件数、`1`–`100`。デフォルトは `20`
`status`	string	いいえ	`pending`、`generating`、`uploading`、`success`、`failed` で絞り込みます
`keyword`	string	いいえ	タスクの `text` に対するあいまい一致。最大 64 文字

レスポンス：

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "id": "68e780390fc5c9a54f695a7e",
        "status": "success",
        "model": "listenhub-voice-1.0",
        "audioUrl": "https://assets.listenhub.ai/listenhub-voice/68e780390fc5c9a54f695a7e.mp3",
        "audioDuration": 18.4,
        "creditCharged": 12,
        "creditRefunded": 0,
        "createdAt": 1730000000000,
        "updatedAt": 1730000040000
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}

各 item は単一タスクを照会すると同じフィールドを持ちます。

エラー

ビジネスエラーは HTTP 400 を返し、具体的なコードはトップレベルの code フィールドに入ります。

コード	意味
`33001`	タスクが見つかりません（または現在の API ユーザーのものではありません）
`33002`	`speaker` のボイス項目に対応するボイスが見つかりません
`33003`	生成サービスが利用できません
`33004`	パラメータが不正です（例：`voices` と `image` を同時に送信、ボイス項目で `id` と `url` を混在）
`33005`	ボイスが多すぎます（最大 3 件）
`33006`	クレジットが不足しています
`33007`	レート制限に達しました
`33008`	生成がタイムアウトしました
`33009`	ユーザーごとの同時実行上限に達しました

HTTP ステータス	意味
`400`	パラメータ不正またはビジネスエラー — 上記の `33xxx` コードを参照
`429`	レート制限を超過（`/generate` はユーザーごとに 5 RPM）

クレジット

クレジットは送信時に予約され、success で確定し、failure の場合は自動的に返還されます。各タスクは照合用に creditCharged（実際に消費された分）と creditRefunded（失敗時に返還された分）を返します。課金対象となる長さは audioDuration です。現在の残高は GET /v1/user/subscription で確認できます。クレジットと機能の対応関係はクレジットと料金を参照してください。

このページの内容