Image to Image API

I-edit at baguhin ang mga larawan sa iyong sariling application. Magpadala ng mga reference na larawan at isang text prompt, at gagawa ang mga AI model ng Meshy ng bagong larawan mula sa mga ito.

Gumagawa ang Image to Image ng mga larawan. Upang gumawa ng 3D model ng nilalaman ng isang larawan, gamitin ang Image to 3D. Upang gumawa ng isang bagay na maaari mong hawakan o i-print mula sa isang larawan, gamitin ang Creative Lab APIs. Gumagawa ang mga ito ng isang prototype na larawan at pagkatapos ay bumubuo ng 3D model mula rito, halimbawa ng isang keychain, fridge magnet, figure, lampara, o keycap.

POST/openapi/v1/image-to-image

Gumawa ng Image to Image na gawain

Gumagawa ng Image to Image na gawain. Tumatakbo ang gawain sa background. Para malaman kung gaano katagal karaniwang tumatagal ang isang gawain, tingnan ang Processing times.

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"
}

Mga Parameter

Name
ai_model
Type
string
Kinakailangan
Description
Ang AI model na gumagawa ng larawan. Iba-iba ang presyo depende sa model. Tingnan ang Pricing.
Mga available na halaga:
- nano-banana: ang standard na model
- nano-banana-2: mas may kakayahan kumpara sa nano-banana
- nano-banana-2-lite: isang lite na bersyon ng nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: ang Pro na model, na may mas mataas na kalidad. Kailangan nito ng Pro plan pataas. Sa mas mababang plan, nagbabalik ito ng 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)
Name
prompt
Type
string
Kinakailangan
Description
Tekstong naglalarawan sa pag-edit o transformasyon na ilalapat sa mga reference na larawan.

Name
input_task_id
Type
string
Kinakailangan
Description
Kinakailangan maliban kung magpadala ka ng reference_image_urls. Ang ID ng isang Text to Image o Image to Image na gawain na ang mga larawan ay gagamitin bilang mga reference, kasama na ang mga multi-view na gawain. Dapat ang gawain ay isa na ginawa mo gamit ang API at may status na SUCCEEDED.
Ginagamit ng Meshy ang bawat larawang nagawa ng gawain. Ang isang single-image na gawain ay nagbibigay ng isang reference na larawan, at ang isang multi-view na gawain ay nagbibigay ng isa bawat view. Kaya ang isang task ID ay maaaring punan ang ilan sa limang reference slot.
Ang gawain ay dapat nasa loob pa rin ng asset retention period. Pagkatapos itong mag-expire, ang ID nito ay magbabalik ng 404.

Name
reference_image_urls
Type
array
Kinakailangan
Description
Kinakailangan maliban kung magpadala ka ng input_task_id. Isa hanggang limang reference na larawan na ie-edit, bawat isa ay isang public URL o data URI, halimbawa data:image/jpeg;base64,<your base64-encoded image data>. Ang isang walang laman na array, o higit sa limang larawan, ay nagbabalik ng 400. Kung magpadala ka ng pareho, gagamitin ng Meshy ang input_task_id.
Dapat ang bawat larawan ay isang .jpg, .jpeg, .png, o .webp na file na hindi hihigit sa 20 MB, at hindi bababa sa 32 pixels bawat gilid.

Name
generate_multi_view
Type
boolean
default false
Description
Kung gagawa ng multi-view na larawan na nagpapakita ng subject mula sa ilang anggulo. Kapag true, hindi ka maaaring magpadala ng aspect_ratio. Ang pagpapadala ng pareho ay nagbabalik ng 400.
Name
aspect_ratio
Type
string
default 1:1
Description
Ang aspect ratio ng output na larawan. Ang mga halagang maaari mong ipadala ay depende sa ai_model.
Mga available na halaga:
- 1:1: parisukat
- 16:9: widescreen landscape
- 9:16: widescreen portrait
- 4:3: standard landscape
- 3:4: standard portrait
- 3:2: landscape, GPT Image na mga model lamang
- 2:3: portrait, GPT Image na mga model lamang
Ang GPT Image na mga model ay gpt-image-2, gpt-image-2-5-flare, at gpt-image-2-5-sunburst. Sa isang nano-banana na model, ang 3:2 at 2:3 ay nagbabalik ng 400.
Name
remove_background
Type
boolean
default false
Description
Kung aalisin ang background. Kapag true, ibinabalik ng Meshy ang output na larawan bilang isang transparent na RGBA PNG, para mailagay mo ang subject sa anumang background.

Ibinabalik

Ang result field ng tugon ay naglalaman ng ID ng bagong Image to Image na gawain.

Mga mode ng pagkabigo

Name
400 - Bad Request
Description
Hindi matatakbo ang request. Sinasabi ng error message kung aling problema ang natagpuan nito. Halimbawa:
- Nawawalang parameter: Isang kinakailangang parameter, tulad ng ai_model o prompt, ay nawawala, o hindi ipinadala ang reference_image_urls ni ang input_task_id.
- Hindi valid na input task: Hindi tumuturo ang input_task_id sa isang magagamit na gawain. Dapat itong isang SUCCEEDED na Text to Image o Image to Image na gawain, kasama na ang multi-view, na may output na larawan pa rin. Tinatanggihan ng Meshy ang isang gawain ng ibang uri, isang gawain na hindi nagtagumpay, at isang gawain na ang lahat ng larawan nito ay nag-expire na.
- Hindi valid na image format: Isa o higit pa sa mga reference na larawan ay wala sa suportadong format.
- Hindi maabot na URL: Hindi ma-download ng Meshy ang isa o higit pa sa mga reference_image_urls na larawan.
- Masyadong malaki ang larawan: Isa o higit pa sa mga reference_image_urls na larawan ay lumalampas sa 20 MB.
- Masyadong maliit ang larawan: Isa o higit pa sa mga reference_image_urls na larawan ay may gilid na mas maikli sa 32 pixels.
- Hindi valid na parameter: Ang aspect_ratio ay hindi isa sa mga halagang sinusuportahan ng napiling ai_model.
- Salungatan: Nagpadala ang request ng aspect_ratio kasama ang generate_multi_view: true.
Ayusin ang request, pagkatapos ay ipadala muli. Tingnan ang Errors.
Name
401 - Unauthorized
Description
Nawawala o hindi valid ang API key. Tingnan ang Authorization header.
Name
402 - Payment Required
Description
Hindi matatakbo ng account ang gawaing ito. Halimbawa:
- Free plan: Ang paggawa ng gawain ay nangangailangan ng bayad na plan. I-upgrade ang iyong plan sa iyong subscription settings, pagkatapos ay subukan muli.
- Hindi sapat na credits: Wala ang account ng sapat na credits para sa gawaing ito, o naabot ng account ang isang limitasyon sa credit.
- Kinakailangang plan: Ginagamit ng request ang nano-banana-pro sa isang plan na mas mababa sa Pro.
Suriin ang iyong credit balanse at plan, pagkatapos ay subukan muli.
Name
404 - Not Found
Description
Ang input_task_id ay hindi tumutugma sa isang gawain sa iyong account. Ang isang gawaing hindi umiiral at ang isang gawaing nabibilang sa ibang account ay nagbabalik ng parehong tugon. Suriin ang ID.
Name
429 - Too Many Requests
Description
Nalampasan mo ang iyong rate limit. Maghintay, pagkatapos ay subukan muli. Tingnan ang Rate limits.

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

Kumuha ng Image to Image task

Nagbabalik ng Image to Image task batay sa ID nito.

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=***"
  ]
}

Mga Parameter

Name
id
Type
path
Description
Ang task ID mula sa create response.

Ibinabalik

Ang Image to Image task object.

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

Mag-delete ng Image to Image task

Permanenteng binubura ang isang Image to Image task, kasama ang mga imahe at data nito. Hindi na puwedeng i-undo ang isang pagbura.

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."
}

Mga path parameter

Name
id
Type
path
Description
Ang ID ng task na ibubura.

Status ng task

Kapag binura ang isang PENDING na task, ire-refund ang mga credits na ginamit nito noong ginawa mo ito.

Hindi puwedeng burahin ang isang IN_PROGRESS na task. Magbabalik ang request ng 409 Conflict, at magpapatuloy pa rin ang pagtakbo ng task. Hindi nagre-refund ang Meshy para sa isang task na nagsimula na, kaya kung ito ay burahin mo, mawawalan ka parehong ng credits at ng resulta. Hintayin itong umabot sa SUCCEEDED, FAILED, o CANCELED, bago ito burahin.

Ang pagbura sa isang task na nasa final status (SUCCEEDED, FAILED, o CANCELED) ay hindi nagre-refund ng mga credits nito.

Mga ibinabalik na halaga

200 OK kapag nabura na ang task, o 409 Conflict kapag IN_PROGRESS ang task.

GET/openapi/v1/image-to-image

I-list ang mga Image to Image na gawain

Nagbabalik ng listahan ng iyong mga Image to Image at Text to Image na gawain. Ang type field ng bawat gawain ay nagsasaad kung alin sa dalawa ito.

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=***"
    ]
  }
]

Mga Parameter

Name
page_num
Type
integer
Description
Ang numero ng pahinang ibabalik. Nagsisimula sa at ang default ay 1.
Name
page_size
Type
integer
Description
Ang bilang ng mga gawain bawat pahina, hanggang 100. Ang default ay 10.
Name
sort_by
Type
string
Description
Ang pagkakasunod-sunod ng pag-uuri.
Mga magagamit na halaga:
- +created_at: pinakaluma muna
- -created_at: pinakabago muna

Mga Ibinabalik

Isang paginated na listahan ng mga task object, sa parehong format ng Image to Image task object.

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

I-stream ang isang Image to Image na task

Nagsa-stream ng mga update ng isang Image to Image na task bilang 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=***"
  ]
}

Mga Parameter

Name
id
Type
path
Description
Ang task ID mula sa create response.

Ibinabalik

Isang stream ng Image to Image task objects bilang Server-Sent Events.

Bawat event ay naglalaman ng kumpletong task object, sa parehong anyo na ibinabalik ng Get endpoint. Habang ang task ay PENDING o IN_PROGRESS, wala pang mga halaga ang mga resultang field nito.

Ang Image to Image task object

Ang isang Image to Image task object ay naglalarawan ng isang larawang nabuo mula sa mga reference image at isang text prompt. Ito ang naghahawak ng status, ng progress, at ng mga larawan kapag matagumpay ang task.

Mga Katangian

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
Ang task ID. Ituring itong isang opaque string, at huwag umasa sa anyo nito.
Name
type
Type
string
Description
Ang uri ng task, laging image-to-image.
Name
ai_model
Type
string
Description
Ang AI model na ginamit ng task.
Mga available na halaga:
- 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
Name
prompt
Type
string
Description
Ang text prompt na gumabay sa pag-eedit.
Name
status
Type
string
Description
Ang status ng task, isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, o CANCELED.
Name
progress
Type
integer
Description
Kung gaano karami ang natapos na sa task, bilang porsyento. Ito ay 0 hanggang magsimula ang task at 100 kapag ito ay nagtagumpay.
Name
created_at
Type
timestamp
Description
Oras nang likhain ang task, sa Unix milliseconds.
Name
started_at
Type
timestamp
Description
Oras nang magsimula ang task, sa Unix milliseconds. Wala hanggang magsimula ang task.
Name
finished_at
Type
timestamp
Description
Oras nang matapos ang task, sa Unix milliseconds. Wala hanggang matapos ang task.
Name
expires_at
Type
timestamp
Description
Oras nang mag-expire ang mga resulta ng task, sa Unix milliseconds. Wala hanggang matapos ang task.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga task na nauuna sa pila bago ang task na ito. Makabuluhan lamang ang halagang ito habang PENDING ang task. Hindi isasama ang field na ito kapag ang halaga ay 0.
Name
image_urls
Type
array
Description
Mga URL para sa pag-download ng mga nabuong larawan. Kapag generate_multi_view: true, maghahawak ito ng isang URL bawat view, karaniwan ay tatlo. Kung hindi mahiwalay ng Meshy ang bawat view, mas kaunti ang ibabalik nito, at magtatagumpay pa rin ang task. Kung hindi, isang URL lamang ang hawak nito.
Name
task_error
Type
object
Description
Ang mga detalye ng error kapag nabigo ang task. Ito ay null maliban kung ang status ay FAILED. Tingnan ang Errors.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na ginamit ng task. Naroroon kapag ang status ay PENDING, IN_PROGRESS, o SUCCEEDED. Ito ay 0 para sa isang FAILED na task, dahil ibinabalik ng Meshy ang credits kapag nabigo ang isang task.