Image to Image API

Ang Image to Image API ay isang feature na nagbibigay-daan sa iyo na isama ang mga kakayahan ng Meshy sa AI image editing sa iyong sariling application. Baguhin at i-edit ang mga umiiral na larawan gamit ang mga reference na larawan at text prompts sa pamamagitan ng aming makapangyarihang mga AI model.

Ang endpoint na ito ay gumagawa ng mga larawan. Kung ang layunin ay isang bagay na maaari mong hawakan o i-print — isang keychain, fridge magnet, figure, lampara o keycap mula sa isang larawan — gamitin ang Creative Lab APIs (prototype na larawan → bumuo ng 3D model). Kung ang layunin ay isang 3D model ng nasa larawan, gamitin ang Image to 3D.

POST/openapi/v1/image-to-image

Create an Image to Image Task

Ang endpoint na ito ay nagbibigay-daan sa iyo na gumawa ng bagong Image to Image task. Sumangguni sa The Image to Image Task Object upang makita kung aling mga property ang kasama sa Image to Image task object.

Tumatakbo ang task sa background. Para sa tagal na karaniwang kinakailangan, tingnan ang Processing Times.

Mga Parameter

Name
ai_model
Type
string
Kinakailangan
Description
ID ng modelong gagamitin para sa pagbuo ng imahe.
Mga available na value:
- nano-banana: Standard na modelo (3 credits bawat imahe)
- nano-banana-2: Balanced na modelo na may mas malakas na kakayahan kaysa sa standard (6 credits bawat imahe)
- nano-banana-2-lite: Lite variant ng nano-banana-2 (3 credits bawat imahe)
- nano-banana-pro: Pro na modelo na may pinahusay na kalidad (9 credits bawat imahe)
- gpt-image-2: OpenAI GPT Image 2, isang high-fidelity na image edit model (12 credits bawat imahe)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), isang high-fidelity na image edit model (12 credits bawat imahe)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), isang high-fidelity na image edit model (12 credits bawat imahe)
Name
prompt
Type
string
Kinakailangan
Description
Isang paglalarawang teksto ng transpormasyon o pag-edit na gusto mong ikapit sa mga reference image.

Isa lamang sa input_task_id o reference_image_urls ang kinakailangan. Kung parehong ibinigay, ang input_task_id ang mananaig (priority).

Name
input_task_id
Type
string
Kinakailangan
Description
Ang ID ng isang nakumpletong image-generation task na ang mga output image ay gagamitin bilang mga reference image. Ang task na ito ay dapat isa sa mga sumusunod na task: Text to Image o Image to Image, kasama ang kanilang mga multi-view variant. Bukod pa rito, dapat itong naisagawa sa pamamagitan ng API at may status na SUCCEEDED.
Ginagamit ang lahat ng output image ng source task. Ang isang single-image task ay nag-aambag ng 1 reference image; ang isang multi-view task ay nag-aambag ng isa para sa bawat nabuong view, kaya ang isang task ID ay maaaring punan ang ilan sa 5 reference slot.
Ang source task ay dapat nasa loob pa rin ng asset retention period — kapag nag-expire na ito, ang ID nito ay magbabalik ng 404.

Name
reference_image_urls
Type
array
Kinakailangan
Description
Isang array ng 1 hanggang 5 reference image na gagamitin para sa image editing task. Kasalukuyan naming sinusuportahan ang mga format na .jpg, .jpeg, .png, at .webp.
Maximum na laki ng file: 20 MB bawat imahe.
May dalawang paraan upang ibigay ang bawat imahe:
- Publicly accessible URL: Isang URL na naa-access mula sa publikong internet.
- Data URI: Isang base64-encoded na data URI ng imahe. Halimbawa ng data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Name
generate_multi_view
Type
boolean
default false
Description
Kapag naka-set sa true, bumubuo ng multi-view na imahe na nagpapakita ng subject mula sa maraming anggulo.
Kapag ang generate_multi_view ay true, hindi maaaring i-set ang parameter na aspect_ratio.
Name
aspect_ratio
Type
string
default 1:1
Description
Tukuyin ang aspect ratio ng output image. Nakadepende ang mga pinapayagang value sa napiling ai_model:
- nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro: 1:1, 16:9, 9:16, 4:3, 3:4
- gpt-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
Mga available na value:
- 1:1: Square na format
- 16:9: Widescreen landscape
- 9:16: Widescreen portrait
- 4:3: Standard na landscape
- 3:4: Standard na portrait
- 3:2: Landscape (sinusuportahan lamang ng mga GPT Image model)
- 2:3: Portrait (sinusuportahan lamang ng mga GPT Image model)
Name
remove_background
Type
boolean
default false
Description
Kapag naka-set sa true, ang output image ay ibinabalik bilang transparent na RGBA PNG na may tinanggal na background, kaya maaari mong i-composite ang subject sa anumang background.

Mga Ibinabalik

Ang result property ng tugon ay naglalaman ng task id ng bagong ginawang Image to Image task.

Mga Mode ng Kabiguan

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Mga karaniwang dahilan:
- Nawawalang parameter: Isang kinakailangang parameter (hal., ai_model, prompt) ang nawawala, o wala sa reference_image_urls o input_task_id ang ibinigay.
- Hindi wastong input task: Ang input_task_id ay dapat tumukoy sa isang SUCCEEDED na Text to Image o Image to Image task (kasama ang multi-view) na may natitirang image output. Tatanggihan ang task ng anumang ibang uri, isa na hindi nagtagumpay, o isa na ang mga imahe ay lahat nag-expire na.
- Hindi wastong format ng imahe: Isa o higit pa sa mga reference image ay hindi suportadong format.
- Hindi maabot na URL: Isa o higit pa sa mga reference_image_urls ay hindi ma-download.
- Masyadong malaki ang imahe: Isa o higit pa sa mga imahe ng reference_image_urls ay lumampas sa 20 MB.
- Hindi wastong parameter: Ang aspect_ratio ay hindi isa sa mga pinapayagang value para sa napiling ai_model.
- Salungatan: Hindi maaaring gamitin nang sabay ang generate_multi_view at aspect_ratio.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Mangyaring suriin ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat na credits upang maisagawa ang task na ito.
Name
404 - Not Found
Description
Ang input_task_id ay hindi tumutukoy sa isang task na pag-aari ng iyong account. Ang isang task na hindi umiiral at isa na pag-aari ng ibang account ay nagbabalik ng parehong tugon.
Name
429 - Too Many Requests
Description
Nalampasan mo na ang iyong rate limit.

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

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

Kunin ang Isang Image to Image Task

Ang endpoint na ito ay nagbibigay-daan sa iyo upang kunin ang isang Image to Image task gamit ang isang valid na task id. Sumangguni sa The Image to Image Task Object upang makita kung aling mga properties ang kasama sa Image to Image task object.

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa Image to Image task na kukunin.

Ibinabalik

Ang response ay naglalaman ng Image to Image task object. Tingnan ang The Image to Image Task Object na seksyon para sa mga detalye.

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

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

Delete an Image to Image Task

Ang endpoint na ito ay permanenteng nagtatanggal ng isang Image to Image task, kasama na ang lahat ng kaugnay na larawan at datos. Ang pagkilos na ito ay hindi na maibabalik.

Path Parameters

Name
id
Type
path
Description
Ang ID ng Image to Image task na tatanggalin.

Katayuan ng Task

Ang isang task na PENDING pa ay tatanggalin at ang mga credits na nagamit noong panahon ng paggawa nito ay ire-refund.

Ang isang task na IN_PROGRESS na ay hindi maaaring tanggalin: ang request ay tatanggihan na may 409 Conflict at ang task ay magpapatuloy na tumakbo. Ang mga credits para sa isang task na nasimulan na ng worker ay hindi na maaaring i-refund, kaya ang pagtanggal nito habang tumatakbo pa ay magiging dahilan ng pagkawala ng iyong credits at ng resulta nito. Hintayin munang maabot nito ang SUCCEEDED, FAILED o CANCELED, bago ito tanggalin.

Ang isang task na nasa terminal na estado (SUCCEEDED, FAILED o CANCELED) ay tatanggalin nang walang refund.

Ibinabalik

Nagbabalik ng 200 OK kapag matagumpay, o 409 Conflict kapag ang task ay IN_PROGRESS.

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

GET/openapi/v1/image-to-image

List Image to Image Tasks

Ang endpoint na ito ay nagbibigay-daan sa iyo upang kumuha ng listahan ng mga Image to Image na gawain.

Mga Parameter

Name
page_num
Type
integer
Description
Numero ng pahina para sa pagination. Nagsisimula at nagde-default sa 1.
Name
page_size
Type
integer
Description
Limitasyon sa laki ng pahina. Nagde-default sa 10 na item. Maximum na pinapayagan ay 100 na item.
Name
sort_by
Type
string
Description
Field na gagamitin para sa pag-sort. Magagamit na mga value:
- +created_at: Isaayos ayon sa oras ng paglikha nang pataas (ascending order).
- -created_at: Isaayos ayon sa oras ng paglikha nang pababa (descending order).

Mga Ibinabalik

Nagbabalik ng isang paginated na listahan ng The Image to Image Task Objects.

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

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

I-stream ang Image to Image Task

Ang endpoint na ito ay nag-i-stream ng real-time na update para sa isang Image to Image task gamit ang Server-Sent Events (SSE).

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa Image to Image task na i-stream.

Mga Ibinabalik

Nagbabalik ng stream ng The Image to Image Task Objects bilang Server-Sent Events.

Para sa mga task na PENDING o IN_PROGRESS, isasama lamang ng response stream ang kinakailangang mga field na progress at status.

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.
// 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

Ang Image to Image Task object ay isang yunit ng trabaho na sinusubaybayan ng Meshy para bumuo ng imahe mula sa mga reference image at isang input na text prompt. Ang object na ito ay may mga sumusunod na properties:

Properties

Name
id
Type
string
Description
Natatanging identifier para sa task. Bagama't gumagamit kami ng k-sortable UUID para sa task ids bilang implementation detail, hindi mo dapat gawin ang anumang pagpapalagay tungkol sa format ng id.
Name
type
Type
string
Description
Ang uri ng image generation task. Para sa mga Image to Image task, ito ay laging magiging image-to-image.
Name
ai_model
Type
string
Description
Ang AI model na ginamit para sa task na ito. Ang mga posibleng value ay nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare, o gpt-image-2-5-sunburst.
Name
prompt
Type
string
Description
Ang text prompt na ginamit upang gabayan ang pagbabago ng imahe.
Name
status
Type
string
Description
Status ng task. Ang mga posibleng value ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress ng task. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0. Kapag matagumpay na ang task, ito ay magiging 100.
Name
created_at
Type
timestamp
Description
Timestamp kung kailan ginawa ang task, sa milliseconds.
Ang timestamp ay kumakatawan sa bilang ng mga millisecond na lumipas mula Enero 1, 1970 UTC, alinsunod sa RFC 3339 standard. Halimbawa, ang Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Ito ay naaangkop sa lahat ng timestamp sa Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp kung kailan nagsimula ang task, sa milliseconds. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0.
Name
finished_at
Type
timestamp
Description
Timestamp kung kailan natapos ang task, sa milliseconds. Kung hindi pa natatapos ang task, ang property na ito ay magiging 0.
Name
expires_at
Type
timestamp
Description
Timestamp kung kailan mag-e-expire ang resulta ng task, sa milliseconds.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga nauunang task.
Ang value ng field na ito ay makabuluhan lamang kung ang status ng task ay PENDING.
Name
image_urls
Type
array
Description
Isang array ng mga nada-download na URL patungo sa mga nabuong imahe. Kapag naka-enable ang generate_multi_view, ang array na ito ay naglalaman ng tatlong image URL na kumakatawan sa iba't ibang viewing angle. Kung hindi, naglalaman ito ng iisang image URL.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa kumpletong reference ng task_error object.
Name
consumed_credits
Type
integer
Description
Ang bilang ng mga credits na nagamit ng task na ito. Naririto kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED task (nire-refund ang credits kapag nabigo).

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
}