> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 音声プレビューの残りを生成

> 現在のアカウントに利用権限がある場合、所有する音声プレビューの残りを生成します。繰り返し呼び出しても文字数を追加消費せず、完成した音声を返します。

現在のアカウントに利用権限がある場合、所有する音声プレビューの残りを生成します。繰り返し呼び出しても文字数を追加消費せず、完成した音声を返します。

```http theme={null}
POST https://api.voicecheap.ai/v1/actions/tts_continue
```

## 認証と権限

**x-api-key** `string` *required*

このヘッダーに VoiceCheap API キーを指定してください。同じ API キーを Authorization: Bearer で送信することもできます。OAuth アクセストークンは MCP
でのみ使用でき、この REST エンドポイントでは使用できません。

必要な権限: `tts:write`.

有効な有料サブスクリプションが必要です。権限によってチーム内のロール、リソースの所有権、メディアクレジット、プランの制限が変わることはありません。

## パラメーター

**requestId** `string`

トランスポート境界では任意です。省略すると、検証前にサーバーが識別子を補完します。レスポンスを受信できなかった場合に安全に復旧できるよう、固定の UUID v4 を指定してください。

形式: "uuid". パターン: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$`.

**historyId** `string` *required*

tts\_generate または tts\_list が返す履歴ID。

パターン: `^(free-)?[0-9a-f]{64}$`.

> [accordion] 完全な入力スキーマ
>
> 以下の JSON Schema は、ディスカバリーで公開される正確なフィールド名、ネストされた型、デフォルト値、範囲、許容値を保持しています。フィールド間の追加ルールは操作の注意事項に記載されています。
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "requestId": {
>       "description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries.",
>       "type": "string",
>       "format": "uuid",
>       "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
>     },
>     "historyId": {
>       "type": "string",
>       "pattern": "^(free-)?[0-9a-f]{64}$",
>       "description": "History ID returned by tts_generate or tts_list."
>     }
>   },
>   "required": ["historyId"],
>   "additionalProperties": false
> }
> ```

## 冪等性

変更操作ごとに、requestId または Idempotency-Key HTTP ヘッダーに UUID v4 を指定してください。ネットワーク障害後の再試行では、同じ識別子と同一の引数を使用します。両方を指定する場合は一致させる必要があります。保存済みリクエストを再取得しても、操作は再実行されず、月間呼び出し回数も追加で消費されません。失敗または中断したリクエストは自動的には再開されません。

すべての変更操作は、再試行時に同じリクエストがまだ実行中であれば、通常の初回実行が同期処理であっても HTTP 202 を返す場合があります。実行が完了していても resultStored が false の場合、再試行では元の結果ではなく、保存済みリクエストの状態を HTTP 200 で返します。出力は対応するドメインの履歴、結果、またはダウンロードアクションで取得してください。

## リクエスト例

例に記載されたリソース識別子とメディアキーを、ご自身のアカウントで返された値に置き換えてください。同じ変更操作を再試行する場合は、リクエスト識別子を変更しないでください。

```bash cURL theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/tts_continue' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","historyId":"free-ebdb6d6f77433edf7c0169994cdce394f1c9c366e4d98cd4762a037cadea0ae4"}'
```

```javascript JavaScript theme={null}
const input = {
  requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
  historyId: 'free-ebdb6d6f77433edf7c0169994cdce394f1c9c366e4d98cd4762a037cadea0ae4',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/tts_continue', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.VOICECHEAP_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.voicecheap.ai/v1/actions/tts_continue",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "historyId": "free-ebdb6d6f77433edf7c0169994cdce394f1c9c366e4d98cd4762a037cadea0ae4"},
    timeout=120,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
```

## レスポンス

この操作は実行中に HTTP 202 を返します。requestId を保存し、その識別子と元の操作名を指定して action\_request\_get をポーリングしてください。ポーリングの状態は running、completed、failed、interrupted です。完了した結果が別のメディアジョブを示す場合は、その操作に対応するステータスまたは出力取得アクションで処理を続けてください。

所有するアプリプレビューの全体音声について、完了後のメタデータ。元の historyId が維持されます。

```json HTTP 202 theme={null}
{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "status": "running",
    "pollAction": "action_request_get",
    "pollAfterSeconds": 5
  },
  "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
```

```json HTTP 200 theme={null}
{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "historyId": "free-ebdb6d6f77433edf7c0169994cdce394f1c9c366e4d98cd4762a037cadea0ae4",
    "status": "completed",
    "characterCount": 12,
    "previewEndIndex": null,
    "downloadUrl": "https://files.example.com/completed-preview-speech.mp3"
  },
  "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
```

```json HTTP 202 replay_running theme={null}
{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "tts_continue",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "running",
    "pollAfterSeconds": 5
  },
  "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
```

```json HTTP 200 replay_completed_without_result theme={null}
{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "tts_continue",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "completed",
    "resultStored": false,
    "message": "The action completed. Retrieve its output from the corresponding history or resource action."
  },
  "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
```

## 結果フィールド

| フィールド | 説明 |
| - | - |
| `data.requestId` | 生成アクションに指定した UUID v4。 |
| `data.historyId` | 所有する音声履歴 ID。64文字の小文字16進数で、アプリプレビューには任意で free- 接頭辞が付きます。 |
| `data.status` | 音声の結果が準備できた場合は completed。 |
| `data.characterCount` | 前後の空白を除いた入力テキスト全体の文字数。 |
| `data.previewEndIndex` | 部分プレビュー音声の文字境界。完全な音声の場合は null。有料の連携生成では完全な音声が返されます。 |
| `data.downloadUrl` | 一時的な MP3 ダウンロード URL。tts\_download で新しい URL を取得してください。 |

## リクエストの復旧とポーリング

接続が切断された後も同じ識別子を使用してください。resultStored が false の場合は、対応する履歴、結果、またはダウンロードアクションで出力を取得します。進捗を確認するためだけに、別の生成を開始しないでください。

```bash theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","operation":"tts_continue"}'
```

```json HTTP 200 theme={null}
{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "tts_continue",
    "status": "completed",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "resultStored": true,
    "result": {
      "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
      "historyId": "free-ebdb6d6f77433edf7c0169994cdce394f1c9c366e4d98cd4762a037cadea0ae4",
      "status": "completed",
      "characterCount": 12,
      "previewEndIndex": null,
      "downloadUrl": "https://files.example.com/completed-preview-speech.mp3"
    }
  }
}
```

## 操作の注意事項

* この変更操作には UUID v4 requestId を使用し、再試行時も同じ引数で再利用してください。長時間実行アクションは最初に running のリクエストを返します。この例は、action\_request\_get で取得できる完了済みハンドラー結果です。
* アップグレード後、アプリまたは tts\_list から、所有する既存プレビューの historyId を使用してください。このアクションでは新しい無料プレビューを作成できません。
* スクリプトの残り部分は、現在のTTS文字数利用枠に算入されます。同じプレビューの完全版を繰り返しリクエストする場合は、完成済みの音声を再利用し、その文字数を再度消費しません。
* 項目がすでに完了している場合は、現在の音声が返されます。結果の characterCount は元のスクリプト全体の文字数を示し、ロック解除後の previewEndIndex は null になります。
* 読み上げ履歴とカスタム音声は認証済みアカウントに属します。チームの請求設定によって、他のメンバーの読み上げや音声へのアクセス権が付与されることはありません。

## 使用量

正常に実行された呼び出しごとに、月間 API/MCP 呼び出し回数を 1 回消費します。メディアクレジットと、その操作固有の生成枠も適用されます。

## エラー

| HTTP ステータス | コード | 意味または対処方法 |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | access\_token または api\_key クエリパラメーターに認証情報が指定されています。認証情報はヘッダーで送信してください。 |
| 400 | `IDEMPOTENCY_CONFLICT` | Idempotency-Key ヘッダーとリクエストボディの requestId は一致させる必要があります。 |
| 400 | `INVALID_REQUEST_ID` | UUID v4 の requestId または Idempotency-Key を指定してください。 |
| 400 | `VALIDATION_ERROR` | 入力がアクションスキーマと一致しません。フィールドエラーは details を確認してください。 |
| 401 | `API_KEY_EXPIRED` | API キーの有効期限が切れています。 |
| 401 | `INVALID_API_KEY` | 有効期限内の有効な API キーを指定してください。 |
| 401 | `INVALID_CREDENTIAL` | Authorization ヘッダーの形式が不正、または x-api-key と競合しています。 |
| 401 | `MISSING_CREDENTIAL` | 利用可能なヘッダー認証情報が指定されていないか、4096文字を超えています。 |
| 401 | `USER_NOT_FOUND` | 認証情報に対応するアカウントはすでに存在しません。 |
| 403 | `ACCOUNT_UNAVAILABLE` | 操作を実行するアカウントまたは請求対象アカウントが利用できないか、削除中です。 |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | 認証情報のユーザーが複数のチームに属しているため、課金コンテキストが曖昧です。 |
| 403 | `INSUFFICIENT_SCOPE` | 必要な権限をすべて付与するか、別の認証情報を使用してください。 |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | アカウントの連携上限を確認できませんでした。 |
| 403 | `PAID_PLAN_REQUIRED` | アプリプレビューの完成処理を含め、連携経由の音声生成には有料プランが必要です。 |
| 403 | `SUBSCRIPTION_REQUIRED` | 有効な有料サブスクリプションを使用してください。 |
| 403 | `TEAM_OWNER_NOT_FOUND` | 実効的なチームオーナーのアカウントが見つかりませんでした。 |
| 404 | `TEXT_TO_SPEECH_HISTORY_NOT_FOUND` | 音声履歴項目が存在しないか、別のアカウントに属しています。 |
| 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | このアカウントでは、すでに 10 件の連携アクションが実行中です。新しいアクションを開始する前に、既存のリクエストをポーリングしてください。 |
| 409 | `IDEMPOTENCY_CONFLICT` | 識別子を再利用する場合は、同じ操作と引数でのみ使用してください。 |
| 409 | `TEXT_TO_SPEECH_GENERATION_IN_PROGRESS` | プレビューの完全版への処理はまだ実行中です。 |
| 409 | `TEXT_TO_SPEECH_REQUEST_CONFLICT` | 内部のプレビュー完了リクエストが保存済みの入力と競合しています。 |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | 月次リセットを待つか、プランを変更してください。 |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Retry-After がある場合は指定時間を待ち、バックオフを使用してください。 |
| 429 | `TEXT_TO_SPEECH_CHARACTER_LIMIT_REACHED` | 残りのスクリプトに対して、プラン付属分と購入済みの TTS 文字数が不足しています。 |
| 500 | `INTERNAL_ERROR` | 変更操作を再試行するか判断する前に、保存済みリクエストの状態とリソースの履歴を確認してください。 |
| 502 | `INTERNAL_ERROR` | アクションを完了できないか、結果を確認できませんでした。別の生成を開始する前に、リクエストの状態とリソースの履歴を確認してください。 |
| 503 | `ACTION_RESULT_UNAVAILABLE` | アクションは実行されましたが、結果を保存できませんでした。新しい生成を開始する前に、保存済みリクエストの状態とリソース履歴を確認してください。 |
| 503 | `SERVER_RESTARTING` | サーバーが再起動中です。少し待ってから再試行し、変更操作では同じリクエスト識別子を使用してください。 |

```json theme={null}
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This credential does not permit the requested action.",
  "status": 403,
  "details": {
    "requiredScopes": ["tts:write"]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.