lowpoly は 2026/10/30 に廃止されます。 3D 生成モデルとしての meshy-7 は 2026/12/31 に廃止されます。テクスチャモデルとしては引き続き利用できます。 リクエストエラーを避けるため、これらの日付までにモデルを切り替えてください。 非推奨の一覧を見る

画像から画像 API

ご自身のアプリケーションで画像を編集・変換できます。参照画像とテキストの prompt を送信すると、Meshy の AI モデルがそれらから新しい画像を生成します。


POST/openapi/v1/image-to-image

Create an Image to Image task

画像から画像タスクを作成します。タスクはバックグラウンドで実行されます。タスクに通常どのくらいの時間がかかるかについては、処理時間を参照してください。

Request

POST
/openapi/v1/image-to-image
# 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-2-1: Nano Banana 2.1
    • nano-banana-pro: より高品質なProモデル。Proプラン以上が必要です。それより下位のプランでは402が返されます。
    • gpt-image-2: OpenAI GPT Image 2
    • gpt-image-2-5-flare: OpenAI GPT Image 2.5(Flare)
    • gpt-image-2-5-sunburst: OpenAI GPT Image 2.5(Sunburst)
    • gpt-image-2-6-flare: OpenAI GPT Image 2.6(Flare)
    • gpt-image-2-6-sunburst: OpenAI GPT Image 2.6(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>)である必要があります。空の配列、または5枚を超える画像を送信すると400が返されます。両方を送信した場合、Meshyはinput_task_idを使用します。

    各画像は、最大20MBの.jpg、.jpeg、.png、または.webpファイルで、各辺が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、gpt-image-2-6-flare、gpt-image-2-6-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ピクセル未満です。
    • 無効なパラメータ: aspect_ratioが選択したai_modelがサポートする値のいずれでもありません。
    • 競合: リクエストがgenerate_multi_view: trueとともにaspect_ratioを送信しています。

    リクエストを修正してから再送信してください。エラーを参照してください。

  • 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

    レート制限を超えました。しばらく待ってから再試行してください。レート制限を参照してください。


GET/openapi/v1/image-to-image/:id

Image to Imageタスクを取得する

IDを指定してImage to Imageタスクを返します。

Request

GET
/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
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。

戻り値

Image to Imageタスクオブジェクト。


DELETE/openapi/v1/image-to-image/:id

画像から画像タスクを削除する

画像から画像タスクを、その画像やデータごと完全に削除します。削除を取り消すことはできません。

Request

DELETE
/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
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 が返されます。


GET/openapi/v1/image-to-image

Image to Image タスクの一覧を取得

あなたの Image to Image および Text to Image タスクの一覧を返します。各タスクの type フィールドで、どちらのタスクであるかが示されます。

Request

GET
/openapi/v1/image-to-image
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 タスクオブジェクトと同じ形式の、ページ分割されたタスクオブジェクトの一覧です。


GET/openapi/v1/image-to-image/:id/stream

画像から画像タスクをストリーミングする

画像から画像タスクの更新を Server-Sent Events (SSE) としてストリーミングします。

Request

GET
/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream
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,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ],
  "task_error": null,

  "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-banana
    • nano-banana-2
    • nano-banana-2-lite
    • nano-banana-2-1
    • nano-banana-pro
    • gpt-image-2
    • gpt-image-2-5-flare
    • gpt-image-2-5-sunburst
    • gpt-image-2-6-flare
    • gpt-image-2-6-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ミリ秒)。タスクが開始するまでは存在しません。

  • Name
    finished_at
    Type
    timestamp
    Description

    タスクが終了した時刻(Unixミリ秒)。タスクが終了するまでは存在しません。

  • Name
    expires_at
    Type
    timestamp
    Description

    タスクの結果が期限切れになる時刻(Unixミリ秒)。タスクが終了するまでは存在しません。

  • Name
    preceding_tasks
    Type
    integer
    Description

    このタスクより前にキューに並んでいるタスクの数。この値はタスクが PENDING の間のみ意味を持ちます。値が 0 の場合、このフィールドは省略されます。

  • Name
    image_urls
    Type
    array
    Description

    生成された画像のダウンロードURL。generate_multi_view: true の場合、ビューごとに1つのURLを保持し、通常は3つです。Meshyがすべてのビューを分離できない場合は、より少ない数を返しますが、それでもタスクは成功します。それ以外の場合は、1つのURLのみを保持します。

  • Name
    task_error
    Type
    object
    Description

    タスクが失敗した場合のエラー詳細。ステータスが FAILED でない限り null です。エラー を参照してください。

  • Name
    consumed_credits
    Type
    integer
    Description

    タスクが使用したクレジット数。ステータスが PENDING、IN_PROGRESS、または SUCCEEDED の場合に存在します。FAILED タスクでは 0 です。これは、タスクが失敗した場合にMeshyがクレジットを返金するためです。