テキストから画像 API
MeshyのAIモデルを使って、テキストのpromptから画像を生成します。
テキストから画像は画像を生成します。画像から3Dモデルを作成するには、画像から3Dをご利用ください。写真から手に取れる、または印刷できるオブジェクトを作成するには、Creative Lab APIをご利用ください。これらは、prototype画像を生成した後、そこから3Dモデル（たとえばキーホルダー、冷蔵庫マグネット、フィギュア、ランプ、キーキャップなど）を構築します。
Text to Imageタスクを作成する
Text to Imageタスクを作成します。タスクはバックグラウンドで実行されます。タスクに通常かかる時間については、処理時間を参照してください。
Request
# Generate an image from a text prompt
curl https://api.meshy.ai/openapi/v1/text-to-image \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"ai_model": "nano-banana",
"prompt": "A majestic dragon soaring through clouds at sunset",
"aspect_ratio": "16:9"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
パラメータ
- Name
- ai_model
- Type
- string
- 必須
- Description
画像を生成するAIモデルです。料金はモデルによって異なります。料金については、料金を参照してください。
利用可能な値:
nano-banana: 標準モデルnano-banana-2:nano-bananaより高性能nano-banana-2-lite:nano-banana-2の軽量版nano-banana-pro: より高品質なProモデルです。Proプラン以上が必要です。それより下位のプランでは402が返されます。gpt-image-2: OpenAI GPT Image 2gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare)gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst)
- Name
- prompt
- Type
- string
- 必須
- Description
生成する画像を説明するテキストです。詳細な説明にするほど良い結果が得られます。
- Name
- generate_multi_view
- Type
- boolean
- デフォルト false
- Description
被写体を複数の角度から示すマルチビュー画像を生成するかどうかです。これが
trueの場合、aspect_ratioを送信できません。両方を送信すると400が返されます。
- Name
- pose_mode
- Type
- string
- Description
キャラクターのポーズで、
a-poseまたはt-poseです。ポーズなしにする場合は指定しないでください。ポーズの動作は
ai_modelによって異なります:nano-banana-2とnano-banana-2-lite: Meshyは選択したモデルをそのまま使用します。画像は常に3:4で、Meshyはaspect_ratioを無視します。nano-bananaとnano-banana-pro: Meshyはnano-banana-proで画像を生成するため、タスクのai_modelはnano-banana-proとして返されます。これにはProプラン以上が必要です。画像は常に3:4で、Meshyはaspect_ratioを無視します。- GPT Imageモデル群(
gpt-image-2、gpt-image-2-5-flare、gpt-image-2-5-sunburst): Meshyは選択したモデルとaspect_ratioをそのまま使用します。
- Name
- aspect_ratio
- Type
- string
- デフォルト 1:1
- Description
画像の形状です。送信できる値は
ai_modelによって異なります。利用可能な値:
1:1: 正方形16:9: ワイドスクリーン横向き9:16: ワイドスクリーン縦向き4:3: 標準横向き3:4: 標準縦向き3:2: 横向き、GPT Imageモデルのみ2:3: 縦向き、GPT Imageモデルのみ
nano-banana系のモデル(nano-banana、nano-banana-2、nano-banana-2-lite、nano-banana-pro)は、3:2と2:3に対して400を返します。
- Name
- remove_background
- Type
- boolean
- デフォルト false
- Description
画像の背景を削除するかどうかです。
trueにすると透過RGBA PNGが返されるため、被写体を任意の背景に配置できます。
戻り値
レスポンスのresultフィールドには、新しいText to ImageタスクのIDが格納されます。
失敗モード
- Name
400 - Bad Request- Description
リクエストを実行できません。エラーメッセージには検出された問題が示されます。例:
- パラメータの欠落:
ai_modelやpromptなど、必須パラメータが欠落しています。 - 不正なパラメータ:
ai_modelまたはaspect_ratioが許可された値のいずれでもありません。 - 競合:
aspect_ratioがgenerate_multi_view: trueと一緒に送信されました。
リクエストを修正してから、再度送信してください。エラーを参照してください。
- パラメータの欠落:
- Name
401 - Unauthorized- Description
APIキーが欠落しているか無効です。
Authorizationヘッダーを確認してください。
- Name
402 - Payment Required- Description
アカウントがこのタスクを実行できません。例:
- 無料プラン: タスクの作成には有料プランが必要です。サブスクリプション設定でプランをアップグレードしてから、再試行してください。
- クレジット不足: アカウントにこのタスクに必要なクレジットが不足している(
Insufficient funds)か、アカウントがクレジット上限に達しています。 - プランが必要: Pro未満のプランで
nano-banana-pro、またはnano-bananaと共にpose_modeを使用するリクエストです(Only Pro and above users can use nano-banana-pro、またはOnly Pro and above users can use A/T pose feature (requires nano-banana-pro))。
クレジット残高とプランを確認してから、再試行してください。
- Name
429 - Too Many Requests- Description
レート制限を超過しました。しばらく待ってから再試行してください。レート制限を参照してください。
Text to Imageタスクを取得する
IDを指定してText to Imageタスクを返します。
Request
curl https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-image",
"ai_model": "nano-banana",
"prompt": "A majestic dragon soaring through clouds at sunset",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"expires_at": 1692771679037,
"image_urls": [
"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
]
}
テキストから画像タスクを削除
テキストから画像タスクを、画像やデータも含めて完全に削除します。削除を取り消すことはできません。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
"message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}
パスパラメータ
- Name
- id
- Type
- path
- Description
削除するタスクのID。
タスクのステータス
PENDING のタスクを削除すると、作成時に使用したクレジットが返還されます。
IN_PROGRESS のタスクは削除できません。リクエストは 409 Conflict を返し、
タスクは実行され続けます。Meshyは開始済みのタスクに対してクレジットを返還しないため、
削除するとクレジットと結果の両方を失うことになります。SUCCEEDED、FAILED、CANCELED
のいずれかの状態になるまで待ってから削除してください。
最終ステータス（SUCCEEDED、FAILED、CANCELED）にあるタスクを削除しても、
クレジットは返還されません。
レスポンス
タスクが削除された場合は 200 OK、タスクが IN_PROGRESS の場合は 409 Conflict
が返されます。
Text to Image タスクの一覧を取得
あなたの Text to Image および Image to Image タスクの一覧を返します。各タスクの type フィールドで、どちらのタスクであるかがわかります。
Request
curl https://api.meshy.ai/openapi/v1/text-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-image",
"ai_model": "nano-banana",
"prompt": "A majestic dragon soaring through clouds at sunset",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"expires_at": 1692771679037,
"image_urls": [
"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
]
}
]
パラメータ
- Name
- page_num
- Type
- integer
- Description
返すページ番号です。
1から始まり、デフォルトは1です。
- Name
- page_size
- Type
- integer
- Description
ページあたりのタスク数で、最大
100です。デフォルトは10です。
- Name
- sort_by
- Type
- string
- Description
ソート順です。
使用可能な値：
+created_at: 古い順-created_at: 新しい順
戻り値
Text to Image タスクオブジェクトと同じ形式の、タスクオブジェクトのページネーションされた一覧です。
Stream a Text to Image task
Text to Imageタスクの更新をServer-Sent Events（SSE）としてストリーミングします。
Request
curl -N https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// Error event example
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-image",
"ai_model": "nano-banana",
"prompt": "A majestic dragon soaring through clouds at sunset",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"expires_at": 1692771679037,
"image_urls": [
"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
]
}
パラメータ
- Name
- id
- Type
- path
- Description
作成レスポンスから取得したタスクID。
戻り値
Text to ImageタスクオブジェクトのストリームをServer-Sent Eventsとして返します。
各イベントは、Getエンドポイントが返すものと同じ形式で、タスクオブジェクト全体を保持します。タスクが PENDING または IN_PROGRESS の間は、結果フィールドにはまだ値が入っていません。
Text to Image タスクオブジェクト
Text to Image タスクオブジェクトは、テキストの prompt から画像を生成する1つのタスクを表します。ステータス、progress、そしてタスクが成功した場合の画像URLを保持します。
プロパティ
Example Text to Image Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-image",
"ai_model": "nano-banana",
"prompt": "A majestic dragon soaring through clouds at sunset",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"expires_at": 1692771679037,
"preceding_tasks": 0,
"image_urls": [
"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
],
"task_error": {
"message": ""
},
"consumed_credits": 3
}
- Name
- id
- Type
- string
- Description
タスクID。不透明な文字列として扱い、その形式に依存しないでください。
- Name
- type
- Type
- string
- Description
タスクタイプ。常に
text-to-imageです。
- Name
- ai_model
- Type
- string
- Description
タスクで使用されたAIモデル。
取り得る値:
nano-banananano-banana-2nano-banana-2-litenano-banana-progpt-image-2gpt-image-2-5-flaregpt-image-2-5-sunburst
- Name
- prompt
- Type
- string
- Description
タスク作成時に使用したテキストprompt。
- Name
- status
- Type
- string
- Description
タスクのステータス。
PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELEDのいずれかです。
- Name
- progress
- Type
- integer
- Description
タスクがどの程度完了しているかをパーセンテージで示します。タスクが開始するまでは
0、成功すると100になります。
- Name
- created_at
- Type
- timestamp
- Description
タスクが作成された時刻（Unixミリ秒）。
- Name
- started_at
- Type
- timestamp
- Description
タスクが開始された時刻（Unixミリ秒）。タスクが開始するまでは
0です。
- Name
- finished_at
- Type
- timestamp
- Description
タスクが完了した時刻（Unixミリ秒）。タスクが完了するまでは
0です。
- Name
- expires_at
- Type
- timestamp
- Description
タスクの結果が期限切れになる時刻（Unixミリ秒）。
- Name
- preceding_tasks
- Type
- integer
- Description
キュー内でこのタスクより前にあるタスクの数。この値はタスクが
PENDINGの間のみ意味を持ちます。
- Name
- image_urls
- Type
- array
- Description
生成された画像のダウンロードURL。
generate_multi_view: trueの場合、配列にはビューごとに1つのURL（通常は3つ）が格納されます。Meshyがすべてのビューを分離できない場合、より少ない数が返されますが、その場合もタスクは成功したままです。それ以外の場合は、URLが1つ格納されます。
- Name
- task_error
- Type
- object
- Description
タスクが失敗した場合のエラー詳細。エラーを参照してください。
- Name
- consumed_credits
- Type
- integer
- Description
タスクが使用したクレジット数。ステータスが
PENDING、IN_PROGRESS、SUCCEEDEDのいずれかの場合に存在します。FAILEDタスクの場合は0です。タスクが失敗した場合、Meshyはクレジットを返金するためです。