画像から画像 API
ご自身のアプリケーションで画像を編集・変換できます。参照画像とテキストの prompt を送信すると、Meshy の AI モデルがそれらから新しい画像を生成します。
画像から画像は画像を生成します。画像内のものの3Dモデルを作成するには、画像から3Dをご利用ください。写真から手に取ったり印刷したりできるオブジェクトを作成するには、Creative Lab APIをご利用ください。これらはプロトタイプ画像を作成し、そこからキーホルダー、冷蔵庫マグネット、フィギュア、ランプ、キーキャップなどの3Dモデルを構築します。
画像から画像タスクを作成する
画像から画像タスクを作成します。タスクはバックグラウンドで実行されます。タスクに通常どれくらいの時間がかかるかについては、処理時間を参照してください。
Request
# Transform a reference image with a text prompt
curl https://api.meshy.ai/openapi/v1/image-to-image \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"reference_image_urls": [
"<your publicly accessible image url or base64-encoded data URI>"
]
}'
## Using data URI example
curl https://api.meshy.ai/openapi/v1/image-to-image \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"reference_image_urls": [
"data:image/png;base64,${YOUR_BASE64_ENCODED_IMAGE_DATA}"
]
}'
## Chaining from a previous task, instead of passing image URLs
curl https://api.meshy.ai/openapi/v1/image-to-image \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"input_task_id": "<your Text to Image or Image to Image task id>"
}'
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
- input_task_id
- Type
- string
- 必須
- Description
reference_image_urlsを送信しない場合は必須です。参照として使用する画像を生成した、テキストから画像タスクまたは画像から画像タスク(マルチビュータスクを含む)のIDです。このタスクはAPIで作成したもので、ステータスがSUCCEEDEDである必要があります。Meshyはそのタスクが生成したすべての画像を使用します。単一画像タスクは参照画像を1枚提供し、マルチビュータスクはビューごとに1枚ずつ提供します。そのため、1つのタスクIDで、5つある参照画像枠の複数を埋めることができます。
このタスクはアセット保持期間内である必要があります。期限が切れると、そのIDは
404を返します。
- Name
- reference_image_urls
- Type
- array
- 必須
- Description
input_task_idを送信しない場合は必須です。編集対象の参照画像を1〜5枚指定します。各画像は公開URLまたはData URIで指定し、例えばdata:image/jpeg;base64,<your base64-encoded image data>のようになります。空の配列、または6枚以上の画像を送信すると400が返されます。両方を送信した場合、Meshyはinput_task_idを使用します。各画像は
.jpg、.jpeg、.png、.webpのいずれかの形式で、最大20MB、最小32×32ピクセルである必要があります。
- Name
- generate_multi_view
- Type
- boolean
- デフォルト false
- Description
被写体を複数の角度から示すマルチビュー画像を生成するかどうかです。
trueの場合、aspect_ratioを送信することはできません。両方を送信すると400が返されます。
- 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モデルのみ
GPT Imageモデルとは、
gpt-image-2、gpt-image-2-5-flare、gpt-image-2-5-sunburstです。nano-bananaモデルでは、3:2と2:3は400を返します。
- Name
- remove_background
- Type
- boolean
- デフォルト false
- Description
背景を削除するかどうかです。
trueの場合、Meshyは出力画像を透過RGBA PNGとして返すため、被写体を任意の背景に配置できます。
返り値
レスポンスのresultフィールドには、新しく作成された画像から画像タスクのIDが格納されます。
失敗モード
- Name
400 - Bad Request- Description
リクエストを実行できません。エラーメッセージには、検出された問題が示されます。例:
- パラメータの不足:
ai_modelやpromptなどの必須パラメータが不足している、またはreference_image_urlsとinput_task_idのどちらも送信されていません。 - 無効な入力タスク:
input_task_idが使用可能なタスクを指していません。マルチビューを含むSUCCEEDED状態のテキストから画像タスクまたは画像から画像タスクで、画像出力がまだ存在している必要があります。Meshyは、他の種類のタスク、成功していないタスク、画像がすべて期限切れになったタスクを拒否します。 - 無効な画像形式: 1つ以上の参照画像がサポートされていない形式です。
- URLに到達不可: Meshyが1つ以上の
reference_image_urls画像をダウンロードできません。 - 画像が大きすぎる: 1つ以上の
reference_image_urls画像が20MBを超えています。 - 画像が小さすぎる: 1つ以上の
reference_image_urls画像が32×32ピクセルより小さいです。 - 無効なパラメータ:
aspect_ratioが、選択したai_modelがサポートする値のいずれでもありません。 - 競合: リクエストが
aspect_ratioとgenerate_multi_view: trueを同時に送信しています。
リクエストを修正してから再送信してください。エラーを参照してください。
- パラメータの不足:
- Name
401 - Unauthorized- Description
APIキーが不足しているか無効です。
Authorizationヘッダーを確認してください。
- Name
402 - Payment Required- Description
アカウントはこのタスクを実行できません。例:
- 無料プラン: タスクの作成には有料プランが必要です。サブスクリプション設定でプランをアップグレードしてから再試行してください。
- クレジット不足: アカウントにこのタスクを実行するための十分なクレジットがない、またはアカウントがクレジット上限に達しています。
- プランが必要: リクエストがProより下位のプランで
nano-banana-proを使用しています。
クレジット残高とプランを確認してから再試行してください。
- Name
404 - Not Found- Description
input_task_idがアカウント内のどのタスクとも一致しません。存在しないタスクと、別アカウントに属するタスクは同じレスポンスを返します。IDを確認してください。
- Name
429 - Too Many Requests- Description
レート制限を超えました。しばらく待ってから再試行してください。レート制限を参照してください。
Image to Imageタスクを取得する
IDを指定してImage to Imageタスクを返します。
Request
curl https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-image",
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"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/image-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 が返されます。
Image to Image タスクの一覧を取得
あなたの Image to Image および Text to Image タスクの一覧を返します。各タスクの type フィールドで、どちらのタスクであるかが示されます。
Request
curl https://api.meshy.ai/openapi/v1/image-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-image",
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"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: 新しい順
戻り値
Image to Image タスクオブジェクトと同じ形式の、ページ分割されたタスクオブジェクトの一覧です。
画像から画像タスクをストリーミングする
画像から画像タスクの更新を Server-Sent Events (SSE) としてストリーミングします。
Request
curl -N https://api.meshy.ai/openapi/v1/image-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": "image-to-image",
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"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です。
返り値
画像から画像タスクオブジェクトのストリームを Server-Sent Events として返します。
各イベントには、Get エンドポイントが返すものと同じ形式で、タスクオブジェクト全体が含まれます。タスクが PENDING または IN_PROGRESS の間は、結果フィールドにはまだ値がありません。
画像から画像タスクオブジェクト
画像から画像タスクオブジェクトは、参照画像とテキストprompt（プロンプト）から生成された1つの画像を表します。タスクが成功すると、ステータス、progress、そして画像を保持します。
プロパティ
Example Image to Image Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-image",
"ai_model": "nano-banana",
"prompt": "Transform this into a cyberpunk style artwork",
"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
タスクタイプ。常に
image-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がクレジットを返金するためです。