> ## 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.
# 画像を生成
> 接続先アカウントの画像を生成します。Web アプリと同じメディア利用枠と保護機能が適用されます。返された generationId を保存し、images_download で画像を取得してください。同じリクエストを再試行するときは requestId を再利用します。
接続先アカウントの画像を生成します。Web アプリと同じメディア利用枠と保護機能が適用されます。返された generationId を保存し、images\_download で画像を取得してください。同じリクエストを再試行するときは requestId を再利用します。
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/images_generate
```
## 認証と権限
このヘッダーに VoiceCheap API キーを指定してください。同じ API キーを Authorization: Bearer で送信することもできます。OAuth アクセストークンは MCP
でのみ使用でき、この REST エンドポイントでは使用できません。
必要な権限: `images: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.
テキスト値。
許容値: "square", "landscape", "portrait". デフォルト値: "square".
uploads/\{yourUserId}/ 配下にアップロードしたJPG、PNG、WebPのオブジェクトキー。外部URLは使用できません。
最小文字数: 1. 最大文字数: 512.
以下の 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
},
"aspectRatio": {
"default": "square",
"type": "string",
"enum": ["square", "landscape", "portrait"]
},
"referenceImageKey": {
"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/images_generate' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"61becb70-00d6-4de0-9eb1-05829a0d851c","prompt":"A peaceful coastal village at sunrise, with warm natural light.","aspectRatio":"square","referenceImageKey":"uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png"}'
```
```javascript JavaScript theme={null}
const input = {
requestId: '61becb70-00d6-4de0-9eb1-05829a0d851c',
prompt: 'A peaceful coastal village at sunrise, with warm natural light.',
aspectRatio: 'square',
referenceImageKey: 'uploads/example-user/2502829e-3fde-4aad-b3c7-ce0f779fa2e6-reference.png',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/images_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/images_generate",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "61becb70-00d6-4de0-9eb1-05829a0d851c", "prompt": "A peaceful coastal village at sunrise, with warm natural light.", "aspectRatio": "square", "referenceImageKey": "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 です。完了した結果が別のメディアジョブを示す場合は、その操作に対応するステータスまたは出力取得アクションで処理を続けてください。
画像生成の完了後にハンドラーが返す最終生成メタデータ。画像のバイナリデータ、previewDataUrl、ダウンロード URL は含まれません。
```json HTTP 202 theme={null}
{
"data": {
"requestId": "61becb70-00d6-4de0-9eb1-05829a0d851c",
"status": "running",
"pollAction": "action_request_get",
"pollAfterSeconds": 5
},
"requestId": "61becb70-00d6-4de0-9eb1-05829a0d851c"
}
```
```json HTTP 200 theme={null}
{
"data": {
"generationId": "6224018c7635dcb933ce5c8f7804aea73738dd1c",
"status": "completed",
"aspectRatio": "square",
"width": 1024,
"height": 1024,
"referenceImageCount": 1,
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"expiresAt": 1792749600000
},
"requestId": "61becb70-00d6-4de0-9eb1-05829a0d851c"
}
```
```json HTTP 202 replay_running theme={null}
{
"data": {
"requestId": "61becb70-00d6-4de0-9eb1-05829a0d851c",
"operation": "images_generate",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "61becb70-00d6-4de0-9eb1-05829a0d851c"
}
```
```json HTTP 200 replay_completed_without_result theme={null}
{
"data": {
"requestId": "61becb70-00d6-4de0-9eb1-05829a0d851c",
"operation": "images_generate",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "61becb70-00d6-4de0-9eb1-05829a0d851c"
}
```
## 結果フィールド
| フィールド | 説明 |
| - | - |
| `data.generationId` | images\_get または images\_download にそのまま渡す識別子。 |
| `data.status` | pending、completed、failed、expired のいずれか。有効期限切れは保存されたステータスより優先されます。 |
| `data.aspectRatio` | square、landscape、portrait のいずれか。 |
| `data.width` | 出力の幅（ピクセル）。サイズが利用可能になる前は null。 |
| `data.height` | 出力の高さ（ピクセル）。寸法が未取得の場合は null。 |
| `data.referenceImageCount` | 使用した参照画像数：0 または 1。 |
| `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":"61becb70-00d6-4de0-9eb1-05829a0d851c","operation":"images_generate"}'
```
```json HTTP 200 theme={null}
{
"data": {
"requestId": "61becb70-00d6-4de0-9eb1-05829a0d851c",
"operation": "images_generate",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"generationId": "6224018c7635dcb933ce5c8f7804aea73738dd1c",
"status": "completed",
"aspectRatio": "square",
"width": 1024,
"height": 1024,
"referenceImageCount": 1,
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"expiresAt": 1792749600000
}
}
}
```
## 操作の注意事項
* images:write が必要です。プロンプトは前後の空白を除去した後で10～1200文字である必要があり、生成前に正規化もされます。aspectRatio のデフォルトは square で、landscape または portrait も指定できます。referenceImageKey は最大1つです。
* これは長時間実行アクションです。最初の API/MCP レスポンスは通常 running を返します。ここに示す最終結果を取得するには、operation を images\_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 のリクエストは、自動的には再試行されません。
* このユーザーが一度に生成できる画像は1枚だけです。生成状態は images\_list と images\_get、PNG のバイトデータは images\_download で取得してください。生成の識別子は不透明な文字列です。requestId に置き換えないでください。
## 使用量
正常に実行された呼び出しごとに、月間 API/MCP 呼び出し回数を 1 回消費します。メディアクレジットと、その操作固有の生成枠も適用されます。
## エラー
| HTTP ステータス | コード | 意味または対処方法 |
| - | - | - |
| 400 | `BAD_REQUEST` | サーバーがリクエストの信頼できるネットワークコンテキストを判定できませんでした。 |
| 400 | `CREDENTIAL_IN_QUERY` | access\_token または api\_key クエリパラメーターに認証情報が指定されています。認証情報はヘッダーで送信してください。 |
| 400 | `IDEMPOTENCY_CONFLICT` | Idempotency-Key ヘッダーとリクエストボディの requestId は一致させる必要があります。 |
| 400 | `IMAGE_PROMPT_INVALID` | 正規化後のプロンプトが 10–1200 文字の範囲外です。 |
| 400 | `IMAGE_REFERENCE_INVALID` | 参照画像のバイナリデータが、対応する画像形式、バイト数上限、寸法、またはデコード要件を満たしていません。 |
| 400 | `INVALID_REQUEST_ID` | requestId または Idempotency-Key が UUID v4 ではありません。 |
| 400 | `REFERENCE_IMAGE_INVALID` | 参照キーが安全でない、所有していない、未対応、利用不可、または 8 MiB を超えています。 |
| 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 | `IMAGE_GENERATION_IN_PROGRESS` | この画像リクエスト、または接続済みユーザーの別の画像リクエストがまだ実行中です。 |
| 409 | `IMAGE_REQUEST_ID_REUSED` | 画像リクエストの識別子は、すでに別の入力に関連付けられています。 |
| 422 | `IMAGE_REQUEST_REJECTED` | このプロンプトまたは参照画像から画像を生成できません。内容を変更して、新しいリクエストを送信してください。 |
| 429 | `IMAGE_DAILY_LIMIT_REACHED` | アカウントの1日あたりの画像生成利用枠を使い切っています。 |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | 月次リセットを待つか、プランを変更してください。 |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Retry-After がある場合は指定時間を待ち、バックオフを使用してください。 |
| 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": ["images:write"]
}
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.