画像から画像 API
画像から画像 APIは、MeshyのAI画像編集機能を独自のアプリケーションに統合できる機能です。参照画像とテキストプロンプトを使用して、既存の画像を強力なAIモデルで変換・編集できます。
このエンドポイントは画像を生成します。写真からキーホルダー、冷蔵庫マグネット、フィギュア、ランプ、キーキャップなど、手に取ったり印刷したりできるオブジェクトを目的とする場合は、Creative Lab API（プロトタイプ画像 → 3Dモデル生成）をご利用ください。画像に写っているものの3Dモデルを目的とする場合は、画像から3Dをご利用ください。
Image to Imageタスクを作成する
このエンドポイントを使用すると、新しいImage to Imageタスクを作成できます。Image to Imageタスクオブジェクトに含まれるプロパティについては、The Image to Image Task Objectを参照してください。
タスクはバックグラウンドで実行されます。通常どのくらいの時間がかかるかについては、Processing Timesを参照してください。
パラメータ
- Name
- ai_model
- Type
- string
- 必須
- Description
画像生成に使用するモデルのID。
利用可能な値：
nano-banana: 標準モデル（画像1枚あたり3クレジット）nano-banana-2: 標準より強力な性能を持つバランス型モデル（画像1枚あたり6クレジット）nano-banana-2-lite:nano-banana-2のライト版（画像1枚あたり3クレジット）nano-banana-pro: 品質を強化したProモデル（画像1枚あたり9クレジット）gpt-image-2: OpenAI GPT Image 2、高精細な画像編集モデル（画像1枚あたり12クレジット）gpt-image-2-5-flare: OpenAI GPT Image 2.5（Flare）、高精細な画像編集モデル（画像1枚あたり12クレジット）gpt-image-2-5-sunburst: OpenAI GPT Image 2.5（Sunburst）、高精細な画像編集モデル（画像1枚あたり12クレジット）
- Name
- prompt
- Type
- string
- 必須
- Description
参照画像に適用したい変換や編集内容をテキストで説明したものです。
input_task_idまたはreference_image_urlsのいずれか一方のみが必須です。両方が指定された場合は、input_task_idが優先されます。
- Name
- input_task_id
- Type
- string
- 必須
- Description
出力画像を参照画像として使用する、完了済みの画像生成タスクのID。このタスクは次のいずれかのタスクである必要があります：Text to ImageまたはImage to Image（それらのマルチビュー版を含む）。さらに、APIを通じて実行され、ステータスが
SUCCEEDEDである必要があります。ソースタスクの出力画像はすべて使用されます。 単一画像タスクは参照画像1枚分を提供し、マルチビュータスクは生成されたビューごとに1枚ずつ提供するため、1つのタスクIDだけで5つの参照画像枠のうち複数を埋めることができます。
ソースタスクはアセット保持期間内である必要があります。期限が切れると、そのIDは
404を返します。
- Name
- reference_image_urls
- Type
- array
- 必須
- Description
画像編集タスクに使用する、1〜5枚の参照画像の配列です。現在サポートしている形式は
.jpg、.jpeg、.png、.webpです。最大ファイルサイズ：画像1枚あたり20MB。
各画像の指定方法には2通りあります：
- 一般公開URL：インターネット上から公開アクセス可能なURL。
- Data URI：画像をbase64エンコードしたData URI。Data URIの例：
data:image/jpeg;base64,<your base64-encoded image data>。
- Name
- generate_multi_view
- Type
- boolean
- デフォルト false
- Description
trueに設定すると、複数の角度から被写体を示すマルチビュー画像を生成します。generate_multi_viewがtrueの場合、aspect_ratioパラメータは設定できません。
- Name
- aspect_ratio
- Type
- string
- デフォルト 1:1
- Description
出力画像のアスペクト比を指定します。指定可能な値は、選択した
ai_modelによって異なります：nano-banana、nano-banana-2、nano-banana-2-lite、nano-banana-pro:1:1、16:9、9:16、4:3、3:4gpt-image-2、gpt-image-2-5-flare、gpt-image-2-5-sunburst:1:1、16:9、9:16、4:3、3:4、3:2、2:3
利用可能な値：
1:1: 正方形フォーマット16:9: ワイドスクリーン横長9:16: ワイドスクリーン縦長4:3: 標準横長3:4: 標準縦長3:2: 横長（GPT Imageモデルのみサポート）2:3: 縦長（GPT Imageモデルのみサポート）
- Name
- remove_background
- Type
- boolean
- デフォルト false
- Description
trueに設定すると、出力画像は背景が除去された透明なRGBA PNGとして返されるため、被写体を任意の背景に合成できます。
戻り値
レスポンスのresultプロパティには、新しく作成されたImage to Imageタスクのタスクidが含まれます。
失敗モード
- Name
400 - Bad Request- Description
リクエストが受理できませんでした。主な原因：
- パラメータの欠落：必須パラメータ（例：
ai_model、prompt）が欠落している、またはreference_image_urlsとinput_task_idのどちらも指定されていない。 - 無効な入力タスク：
input_task_idは、画像出力をまだ保持しているSUCCEEDED状態のText to ImageまたはImage to Imageタスク（マルチビューを含む）を参照している必要があります。それ以外の種類のタスク、成功していないタスク、または画像がすべて失効したタスクは拒否されます。 - 無効な画像形式：1つ以上の参照画像がサポートされていない形式です。
- 到達不能なURL：1つ以上の
reference_image_urlsがダウンロードできませんでした。 - 画像が大きすぎる：1つ以上の
reference_image_urlsの画像が20MBを超えています。 - 無効なパラメータ：
aspect_ratioが、選択したai_modelで許可されている値のいずれにも該当しません。 - 競合：
generate_multi_viewとaspect_ratioは同時に使用できません。
- パラメータの欠落：必須パラメータ（例：
- Name
401 - Unauthorized- Description
認証に失敗しました。APIキーを確認してください。
- Name
402 - Payment Required- Description
このタスクを実行するためのクレジットが不足しています。
- Name
404 - Not Found- Description
input_task_idが、お客様のアカウントが所有するタスクを参照していません。存在しないタスクと他のアカウントに属するタスクは、同じレスポンスを返します。
- Name
429 - Too Many Requests- Description
レート制限を超過しました。
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"
}
画像から画像タスクを取得する
このエンドポイントは、有効なタスク id を指定して画像から画像タスクを取得できます。
画像から画像タスクオブジェクトに含まれるプロパティについては、画像から画像タスクオブジェクトを参照してください。
パラメータ
- Name
- id
- Type
- path
- Description
取得対象の画像から画像タスクの一意の識別子です。
戻り値
レスポンスには画像から画像タスクオブジェクトが含まれます。詳細は 画像から画像タスクオブジェクトセクションを確認してください。
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=***"
]
}
画像から画像タスクを削除
このエンドポイントは、関連するすべての画像とデータを含め、画像から画像タスクを完全に削除します。この操作は取り消せません。
パスパラメーター
- Name
- id
- Type
- path
- Description
削除する画像から画像タスクのID。
タスクのステータス
まだ PENDING の状態のタスクは削除され、作成時に消費されたクレジットは
返金されます。
すでに IN_PROGRESS のタスクは削除できません。リクエストは
409 Conflict で拒否され、タスクは実行され続けます。ワーカーがすでに開始している
タスクのクレジットは返金対象外のため、実行中に削除すると
クレジットと結果の両方を失うことになります。SUCCEEDED、FAILED、または
CANCELED の状態になるまで待ってから削除してください。
終了状態（SUCCEEDED、FAILED、または CANCELED）のタスクは
返金なしで削除されます。
戻り値
成功時は 200 OK を返し、タスクが IN_PROGRESS の場合は
409 Conflict を返します。
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 is left 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."
}
Image to Image タスクの一覧を取得
このエンドポイントは、Image to Image タスクの一覧を取得するために使用します。
パラメータ
- Name
- page_num
- Type
- integer
- Description
ページネーション用のページ番号です。
1から始まり、デフォルトは1です。
- Name
- page_size
- Type
- integer
- Description
ページサイズの上限です。デフォルトは
10件です。最大許容数は100件です。
- Name
- sort_by
- Type
- string
- Description
ソートに使用するフィールドです。利用可能な値：
+created_at: 作成日時の昇順でソートします。-created_at: 作成日時の降順でソートします。
返り値
The Image to Image Task Object のページネーションされたリストを返します。
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=***"
]
}
]
Image to Image タスクをストリーミングする
このエンドポイントは、Server-Sent Events（SSE）を使用して Image to Image タスクのリアルタイム更新をストリーミングします。
パラメーター
- Name
- id
- Type
- path
- Description
ストリーミング対象の Image to Image タスクの一意識別子。
レスポンス
Image to Image タスクオブジェクトのストリームを Server-Sent Events として返します。
PENDING または IN_PROGRESS のタスクの場合、レスポンスストリームには必要な progress と status フィールドのみが含まれます。
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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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=***"
]
}
The Image to Image Task Object
Image to Image Task オブジェクトは、参照画像とテキストpromptの入力から画像を生成するために Meshy が追跡する作業単位です。 このオブジェクトには以下のプロパティがあります。
Properties
- Name
- id
- Type
- string
- Description
タスクの一意の識別子です。タスク id の実装の詳細としては k-sortable な UUID を使用していますが、id のフォーマットについていかなる前提も置かないようにしてください。
- Name
- type
- Type
- string
- Description
画像生成タスクの種類です。Image to Image タスクの場合、これは常に
image-to-imageになります。
- Name
- ai_model
- Type
- string
- Description
このタスクで使用された AI モデルです。使用可能な値は
nano-banana、nano-banana-2、nano-banana-2-lite、nano-banana-pro、gpt-image-2、gpt-image-2-5-flare、gpt-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
タスクの progress です。タスクがまだ開始されていない場合、このプロパティは
0になります。タスクが成功すると、100になります。
- Name
- created_at
- Type
- timestamp
- Description
タスクが作成された時刻のタイムスタンプ（ミリ秒）です。
タイムスタンプは、RFC 3339 標準に従い、1970年1月1日 UTC からの経過ミリ秒数を表します。 たとえば、2023年9月1日（金）12:00:00 PM GMT は
1693569600000として表されます。これは Meshy API 内のすべてのタイムスタンプに当てはまります。
- Name
- started_at
- Type
- timestamp
- Description
タスクが開始された時刻のタイムスタンプ（ミリ秒）です。タスクがまだ開始されていない場合、このプロパティは
0になります。
- Name
- finished_at
- Type
- timestamp
- Description
タスクが終了した時刻のタイムスタンプ（ミリ秒）です。タスクがまだ終了していない場合、このプロパティは
0になります。
- Name
- expires_at
- Type
- timestamp
- Description
タスクの結果が期限切れになる時刻のタイムスタンプ（ミリ秒）です。
- Name
- preceding_tasks
- Type
- integer
- Description
先行タスクの数です。
このフィールドの値は、タスクのステータスが
PENDINGの場合にのみ意味を持ちます。
- Name
- image_urls
- Type
- array
- Description
生成された画像のダウンロード可能な URL の配列です。
generate_multi_viewが有効な場合、この配列には異なる視点を表す3つの画像 URL が含まれます。それ以外の場合は、単一の画像 URL が含まれます。
- Name
- task_error
- Type
- object
- Description
失敗したタスクのエラー詳細です。
task_errorオブジェクトの完全なリファレンスについては Errors を参照してください。
- Name
- consumed_credits
- Type
- integer
- Description
このタスクで消費されたクレジット数です。タスクのステータスが
PENDING、IN_PROGRESS、またはSUCCEEDEDの場合に存在します。FAILEDタスクの場合は0を返します（失敗時にはクレジットが返金されます）。
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
}