> ## 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.
# YouTube サムネイルを生成
> Web アプリのメディア利用枠を使用し、接続先アカウントの 1280×720 サムネイルを生成します。同じリクエストを再試行するときは requestId を再利用し、thumbnails_download で結果を取得してください。
Web アプリのメディア利用枠を使用し、接続先アカウントの 1280×720 サムネイルを生成します。同じリクエストを再試行するときは requestId を再利用し、thumbnails\_download で結果を取得してください。
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/thumbnails_generate
```
## 認証と権限
このヘッダーに VoiceCheap API キーを指定してください。同じ API キーを Authorization: Bearer で送信することもできます。OAuth アクセストークンは MCP
でのみ使用でき、この REST エンドポイントでは使用できません。
必要な権限: `thumbnails:write`.
有効な有料サブスクリプションが必要です。権限によってチーム内のロール、リソースの所有権、メディアクレジット、プランの制限が変わることはありません。
## パラメーター
トランスポート境界では任意です。省略すると、検証前にサーバーが識別子を補完します。レスポンスを受信できなかった場合に安全に復旧できるよう、固定の 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}$`.
テキスト値。
最小文字数: 10. 最大文字数: 1200.
値のリスト。要素の構造は完全な入力スキーマを参照してください。
最大要素数: 3. デフォルト値: \[].
以下の JSON Schema は、ディスカバリーで公開される正確なフィールド名、ネストされた型、デフォルト値、範囲、許容値を保持しています。フィールド間の追加ルールは操作の注意事項に記載されています。
```json theme={null}
{
"type": "object",
"properties": {
"requestId": {
"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}$",
"description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries."
},
"prompt": {
"type": "string",
"minLength": 10,
"maxLength": 1200
},
"referenceImageKeys": {
"default": [],
"maxItems": 3,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"description": "An uploaded JPG, PNG or WebP object key under uploads/{yourUserId}/. Remote URLs are not accepted."
}
}
},
"required": ["prompt"],
"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/thumbnails_generate' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"2fcb6b7f-4e5d-421a-b35b-b68548dfd83e","prompt":"A clean YouTube thumbnail showing a mountain sunrise, with the text “A new adventure”.","referenceImageKeys":["uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png"]}'
```
```javascript JavaScript theme={null}
const input = {
requestId: '2fcb6b7f-4e5d-421a-b35b-b68548dfd83e',
prompt: 'A clean YouTube thumbnail showing a mountain sunrise, with the text “A new adventure”.',
referenceImageKeys: ['uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png'],
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/thumbnails_generate', {
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/thumbnails_generate",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e", "prompt": "A clean YouTube thumbnail showing a mountain sunrise, with the text “A new adventure”.", "referenceImageKeys": ["uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png"]},
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 です。完了した結果が別のメディアジョブを示す場合は、その操作に対応するステータスまたは出力取得アクションで処理を続けてください。
生成完了後に返される最終的なサムネイルメタデータ。出力は 1280 × 720 ピクセルです。画像バイト列、previewDataUrl、引き渡しトークンは含まれません。
```json HTTP 202 theme={null}
{
"data": {
"requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e",
"status": "running",
"pollAction": "action_request_get",
"pollAfterSeconds": 5
},
"requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e"
}
```
```json HTTP 200 theme={null}
{
"data": {
"generationId": "109c61cb35dbdc01a94aabb3b1a128519ed1f8823800a7a327b9d8d8c2c0e10b",
"status": "completed",
"width": 1280,
"height": 720,
"referenceImageCount": 1,
"createdAt": 1792144800000,
"updatedAt": 1792144800000,
"expiresAt": 1792749600000
},
"requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e"
}
```
```json HTTP 202 replay_running theme={null}
{
"data": {
"requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e",
"operation": "thumbnails_generate",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e"
}
```
```json HTTP 200 replay_completed_without_result theme={null}
{
"data": {
"requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e",
"operation": "thumbnails_generate",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e"
}
```
## 結果フィールド
| フィールド | 説明 |
| - | - |
| `data.generationId` | thumbnails\_get または thumbnails\_download にそのまま渡す識別子。 |
| `data.status` | completed、expired、または deleted。deleted のレコードは、有効期限を過ぎても deleted のままです。 |
| `data.width` | 出力幅：1280 ピクセル。 |
| `data.height` | 出力の高さ（ピクセル）：720。 |
| `data.referenceImageCount` | 使用した参照画像数：0–3。 |
| `data.createdAt` | 作成時刻（Unix ミリ秒）。 |
| `data.updatedAt` | 最終更新時刻。Unix 時間のミリ秒単位。 |
| `data.expiresAt` | 生成されたサムネイルをダウンロードできなくなる時刻。Unix 時間のミリ秒単位。 |
## リクエストの復旧とポーリング
接続が切断された後も同じ識別子を使用してください。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":"2fcb6b7f-4e5d-421a-b35b-b68548dfd83e","operation":"thumbnails_generate"}'
```
```json HTTP 200 theme={null}
{
"data": {
"requestId": "2fcb6b7f-4e5d-421a-b35b-b68548dfd83e",
"operation": "thumbnails_generate",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"generationId": "109c61cb35dbdc01a94aabb3b1a128519ed1f8823800a7a327b9d8d8c2c0e10b",
"status": "completed",
"width": 1280,
"height": 720,
"referenceImageCount": 1,
"createdAt": 1792144800000,
"updatedAt": 1792144800000,
"expiresAt": 1792749600000
}
}
}
```
## 操作の注意事項
* thumbnails:write が必要です。プロンプトは前後の空白を除去した後で10～1200文字である必要があり、生成前に正規化もされます。referenceImageKeys のデフォルトは \[] で、最大3つのキーを指定できます。
* このアクションは完了まで時間がかかります。最初の API/MCP レスポンスは通常 running を返します。operation に thumbnails\_generate、requestId に同じ値を指定して action\_request\_get をポーリングすると、ここに示す最終結果を取得できます。
* アカウントの通常の1日あたりのサムネイル生成利用枠を使用します。アカウントで新しく作成したサムネイルは作成から7日後に期限切れになります。expiresAt より前に結果をダウンロードしてください。
* 認証情報がチームのコンテキストで接続されている場合も、このアクションは接続ユーザー自身の作成物とアップロードを使用します。
* 参照キーは uploads/\{yourUserId}/ 配下の完了済みアップロードを指し、末尾が .jpg、.jpeg、.png、.webp のいずれかである必要があります。リモート URL、他のユーザーのキー、パストラバーサルのセグメント、バックスラッシュ、パーセントエスケープ、クエリ文字列、フラグメント、制御文字は拒否されます。
* 各参照画像は空でなく、最大 8 MiB（8,388,608 バイト）で、拡張子が示す画像形式としてデコードでき、縦横それぞれ 128–4096 ピクセルである必要があります。デコード後の総ピクセル数にも上限があります。アップロードした参照画像は再利用できます。これらの生成アクションは、アップロード済みファイルを消費も削除もしません。
* UUID v4 の requestId、または HTTP の Idempotency-Key ヘッダーを使用し、再試行時は同一の入力で再利用してください。連携レイヤーは各変更を記録し、再実行せずに記録済みの状態または結果を返します。failed または interrupted のリクエストは、自動的には再試行されません。
* completed 状態のリクエストでは、既存のサムネイルが返される場合があります。以前に failed または interrupted となった連携リクエストは自動で再実行されません。新しいリクエストを開始する前に、リクエストの状態と thumbnails\_list を確認してください。
* メタデータには thumbnails\_get または thumbnails\_list、WebP のバイナリデータには thumbnails\_download を使用してください。生成識別子は不透明な文字列で、requestId ではありません。
## 使用量
正常に実行された呼び出しごとに、月間 API/MCP 呼び出し回数を 1 回消費します。メディアクレジットと、その操作固有の生成枠も適用されます。
## エラー
| HTTP ステータス | コード | 意味または対処方法 |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | access\_token または api\_key クエリパラメーターに認証情報が指定されています。認証情報はヘッダーで送信してください。 |
| 400 | `IDEMPOTENCY_CONFLICT` | Idempotency-Key ヘッダーとリクエストボディの requestId は一致させる必要があります。 |
| 400 | `INVALID_REQUEST_ID` | requestId または Idempotency-Key が UUID v4 ではありません。 |
| 400 | `REFERENCE_IMAGE_INVALID` | 参照キーまたはそのバイナリデータが、所有権、形式、サイズ、寸法、デコードの検証に合格しません。 |
| 400 | `THUMBNAIL_PROMPT_INVALID` | 正規化後のプロンプトが 10–1200 文字の範囲外です。 |
| 400 | `VALIDATION_ERROR` | 引数が不足している、値が未対応、上限を超えている、または厳密な入力スキーマに含まれていません。 |
| 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 | `SUBSCRIPTION_REQUIRED` | 有効な有料サブスクリプションを使用してください。 |
| 403 | `TEAM_OWNER_NOT_FOUND` | 実効的なチームオーナーのアカウントが見つかりませんでした。 |
| 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | このアカウントでは、すでに 10 件の連携アクションが実行中です。新しいアクションを開始する前に、既存のリクエストをポーリングしてください。 |
| 409 | `IDEMPOTENCY_CONFLICT` | このリクエスト識別子は別の引数ですでに使用されています。ヘッダーと本文の識別子が一致しない場合も、同じコードで HTTP 400 を返します。 |
| 409 | `THUMBNAIL_GENERATION_IN_PROGRESS` | このサムネイルリクエストは既に処理中です。 |
| 409 | `THUMBNAIL_REQUEST_FAILED` | このサムネイル生成の試行は以前に失敗しています。新しいリクエストを開始するか判断する前に、状態を確認してください。 |
| 409 | `THUMBNAIL_REQUEST_ID_REUSED` | このサムネイルのリクエスト識別子は、すでに異なる入力に関連付けられています。 |
| 410 | `THUMBNAIL_NOT_FOUND` | このリクエストで以前に完了した結果は、有効期限切れか、利用できなくなっています。 |
| 422 | `THUMBNAIL_REQUEST_REJECTED` | このプロンプトまたは参照からサムネイルを生成できません。内容を変更して新しいリクエストを送信してください。 |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | 月次リセットを待つか、プランを変更してください。 |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Retry-After がある場合は指定時間を待ち、バックオフを使用してください。 |
| 429 | `THUMBNAIL_DAILY_LIMIT_REACHED` | アカウントの 1 日あたりのサムネイル生成利用枠を使い切りました。 |
| 500 | `INTERNAL_ERROR` | 変更操作を再試行するか判断する前に、保存済みリクエストの状態とリソースの履歴を確認してください。 |
| 502 | `INTERNAL_ERROR` | サムネイルの生成または準備に失敗しました。再生成するかを判断する前に、リクエストの状態を確認してください。 |
| 503 | `ACTION_RESULT_UNAVAILABLE` | アクションは実行されましたが、結果を保存できませんでした。新しい生成を開始する前に、保存済みリクエストの状態とリソース履歴を確認してください。 |
| 503 | `INTERNAL_ERROR` | サムネイル生成またはその保存済み結果を一時的に利用できません。再試行する前にリクエストの状態を確認してください。 |
| 503 | `SERVER_RESTARTING` | サーバーが再起動中です。少し待ってから再試行し、変更操作では同じリクエスト識別子を使用してください。 |
```json theme={null}
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["thumbnails:write"]
}
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.