Image to Image API

Ang Image to Image API ay isang feature na nagbibigay-daan sa iyo na i-integrate ang AI image editing capabilities ng Meshy sa iyong sariling application. I-transform at i-edit ang mga umiiral na larawan gamit ang mga reference image at text prompt sa pamamagitan ng aming makapangyarihang AI models.

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 anong mga properties ang kasama sa Image to Image task object.

Mga Parameter

  • Name
    ai_model
    Type
    string
    Kinakailangan
    Description

    ID ng model na gagamitin para sa paggawa ng imahe.

    Mga available na value:

    • nano-banana: Standard na model (3 credits bawat imahe)
    • nano-banana-2: Balanced na model na may mas malakas na kakayahan kaysa sa standard (6 credits bawat imahe)
    • nano-banana-pro: Pro na model 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 pagbabago o pag-edit na gusto mong ilapat 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.

  • Name
    input_task_id
    Type
    string
    Kinakailangan
    Description

    Ang ID ng isang natapos na image-generation task na dapat gamitin ang mga output image nito bilang mga reference image. Ang task na ito ay dapat isa sa mga sumusunod na task: Text to Image o Image to Image, kabilang ang kanilang mga multi-view variant. Bukod pa rito, dapat itong napatakbo sa pamamagitan ng API at may status na SUCCEEDED.

    Lahat ng output image ng source task ay ginagamit. Ang isang single-image task ay nag-aambag ng 1 reference image; ang isang multi-view task ay nag-aambag ng isa bawat nabuong view, kaya ang iisang task ID ay maaaring pumuno ng ilan sa 5 reference slot.

    Ang source task ay dapat nasa loob pa rin ng asset retention period — kapag nag-expire 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 .jpg, .jpeg, at .png na format.

    May dalawang paraan upang magbigay ng bawat imahe:

    • Publicly accessible na URL: Isang URL na naa-access mula sa pampublikong 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 sa subject mula sa maraming anggulo.

    Kapag ang generate_multi_view ay true, hindi maaaring itakda ang aspect_ratio na parameter.

  • Name
    aspect_ratio
    Type
    string
    default 1:1
    Description

    Tukuyin ang aspect ratio ng output image. Ang mga pinapayagang value ay depende sa napiling ai_model:

    • nano-banana, nano-banana-2, 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 landscape
    • 3:4: Standard 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 ibabalik bilang isang transparent RGBA PNG na may background na tinanggal, para maaari mong i-composite ang subject sa anumang background.

Mga Ibinabalik

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

Mga Failure Mode

  • Name
    400 - Bad Request
    Description

    Ang request ay hindi katanggap-tanggap. Karaniwang mga dahilan:

    • Nawawalang parameter: Isang kinakailangang parameter (hal., ai_model, prompt) ang nawawala, o hindi ibinigay ang reference_image_urls o ang input_task_id.
    • Hindi valid na input task: Ang input_task_id ay dapat tumutukoy sa isang SUCCEEDED na Text to Image o Image to Image task (kasama ang multi-view) na mayroon pa ring image output. Ang isang task ng anumang ibang uri, isa na hindi nagtagumpay, o isa na ang mga imahe ay lahat nag-expire na ay tinatanggihan.
    • Hindi valid na image format: Isa o higit pang reference image ang hindi suportadong format.
    • Hindi maabot na URL: Isa o higit pang reference_image_urls ang hindi ma-download.
    • Hindi valid na parameter: Ang aspect_ratio ay hindi isa sa mga pinapayagang value para sa napiling ai_model.
    • Conflict: Ang generate_multi_view at aspect_ratio ay hindi maaaring gamitin nang sabay-sabay.
  • Name
    401 - Unauthorized
    Description

    Nabigo ang authentication. Pakisuri ang iyong API key.

  • Name
    402 - Payment Required
    Description

    Hindi sapat na credits upang isagawa 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

    Lumampas ka na sa 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=***"
  ]
}

Ang Image to Image Task Object

Ang Image to Image Task object ay isang unit ng gawain na sinusubaybayan ng Meshy para makabuo ng imahe mula sa mga reference image at isang text prompt na input. 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 mga task id bilang detalye ng implementasyon, hindi ka dapat gumawa ng anumang palagay 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 palaging image-to-image.

  • Name
    ai_model
    Type
    string
    Description

    Ang AI model na ginamit para sa task na ito. Ang posibleng mga value ay nano-banana, nano-banana-2, 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 posibleng mga 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 nagtagumpay na ang task, ito ay magiging 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp kung kailan nilikha ang task, sa milliseconds.

    Ang isang timestamp ay kumakatawan sa bilang ng mga millisecond na lumipas simula Enero 1, 1970 UTC, alinsunod sa RFC 3339 na pamantayan. 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 sinimulan 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 naunang 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 URL na maaaring i-download para sa mga nabuong imahe. Kapag pinagana ang generate_multi_view, ang array na ito ay naglalaman ng tatlong URL ng imahe na kumakatawan sa iba't ibang anggulo ng pagtingin. Kung hindi, naglalaman ito ng iisang URL ng imahe.

  • 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. Naroroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED na 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
}