Text to Image API

Ang Text to Image API ay isang feature na nagbibigay-daan sa iyo na isama ang mga kakayahan ng Meshy sa AI image generation sa sarili mong application. Gumawa ng mataas na kalidad na mga imahe mula sa mga text prompt gamit ang aming makapangyarihang mga AI model.

Ang endpoint na ito ay gumagawa ng mga imahe. 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 image → bumuo ng 3D model). Kung ang layunin ay isang 3D model ng nasa larawan, gamitin ang Image to 3D.

POST/openapi/v1/text-to-image

Gumawa ng Text to Image Task

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

Ang task ay tumatakbo sa background. Para sa karaniwang tagal nito, tingnan ang Processing Times.

Mga Parameter

Name
ai_model
Type
string
Kinakailangan
Description
ID ng modelo na gagamitin para sa paggawa ng imahe.
Mga magagamit na halaga:
- nano-banana: Standard na modelo (3 credits bawat imahe)
- nano-banana-2: Balanced na modelo na mas malakas kaysa sa standard (6 credits bawat imahe)
- nano-banana-2-lite: Lite na 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 modelo ng imahe (9 credits bawat imahe)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), isang high-fidelity na modelo ng imahe (9 credits bawat imahe)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), isang high-fidelity na modelo ng imahe (9 credits bawat imahe)
Name
prompt
Type
string
Kinakailangan
Description
Isang paglalarawan sa teksto ng imahe na gusto mong buuin. Maging detalyado para sa pinakamagandang resulta.
Name
generate_multi_view
Type
boolean
default false
Description
Kapag itinakda sa true, bubuo ng isang multi-view na imahe na nagpapakita sa subject mula sa maraming anggulo.
Kapag ang generate_multi_view ay true, hindi maaaring itakda ang parameter na aspect_ratio.
Name
pose_mode
Type
string
Description
Tukuyin ang pose mode para sa paggawa ng karakter. Kapag hindi isinama, ang imahe ay bubuuin nang walang anumang pose preset.
Mga magagamit na halaga: a-pose, t-pose
Sa nano-banana, nano-banana-2, nano-banana-2-lite at nano-banana-pro, ang pagtatakda ng pose_mode ay nagpipirmi sa aspect ratio ng output sa 3:4 at anumang aspect_ratio na ipinadala mo ay babalewalain. Pinapanatili ng nano-banana-2 at nano-banana-2-lite ang hinilingang modelo. Sa nano-banana o nano-banana-pro, ang isang posed na imahe ay bubuuin ng nano-banana-pro (ang ai_model ng task ay babasahin bilang nano-banana-pro), na nangangailangan ng Pro plan o mas mataas. Pinapanatili ng mga GPT Image na modelo (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst) ang hinilingang modelo at aspect_ratio.
Name
aspect_ratio
Type
string
default 1:1
Description
Tukuyin ang aspect ratio ng ginawang imahe. Ang mga pinapayagang halaga ay nakadepende 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 magagamit na halaga:
- 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 na modelo)
- 2:3: Portrait (sinusuportahan lamang ng mga GPT Image na modelo)
Name
remove_background
Type
boolean
default false
Description
Kapag itinakda sa true, ang ginawang imahe ay ibabalik bilang isang transparent na RGBA PNG na may tinanggal na background, upang maaari mong i-composite ang subject sa anumang background.

Mga Ibinabalik na Resulta

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

Mga Mode ng Pagkabigo

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Mga karaniwang dahilan:
- Nawawalang parameter: Isang kinakailangang parameter (hal., ai_model, prompt) ay nawawala.
- Hindi wastong parameter: Ang ai_model o aspect_ratio ay hindi isa sa mga pinapayagang halaga.
- Salungatan: Hindi maaaring gamitin nang sabay-sabay ang generate_multi_view at aspect_ratio.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Pakisuri ang iyong API key.
Name
402 - Payment Required
Description
Mga karaniwang dahilan:
- Hindi sapat na credits: Ang iyong account ay walang sapat na credits upang maisagawa ang task na ito (Insufficient funds).
- Kailangan ang plan: Ang nano-banana-pro, o pose_mode kasama ang nano-banana, ay nangangailangan ng Pro plan o mas mataas (Only Pro and above users can use nano-banana-pro, o Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).
Name
429 - Too Many Requests
Description
Lumampas ka sa iyong rate limit.

Request

POST

/openapi/v1/text-to-image

# Generate an image from a text prompt
curl https://api.meshy.ai/openapi/v1/text-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

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

Pagkuha ng Text to Image Task

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

Mga Parameter

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

Ibinabalik

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

Request

GET

/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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/text-to-image/:id

Mag-delete ng Text to Image Task

Ang endpoint na ito ay permanenteng magde-delete ng isang Text to Image task, kabilang ang lahat ng kaugnay na mga larawan at data. Hindi na mababawi ang aksyong ito.

Path Parameters

Name
id
Type
path
Description
Ang ID ng Text to Image task na ide-delete.

Status ng Task

Ang isang task na nasa PENDING pa ay made-delete at ire-refund ang mga credits na nagastos nang gawin ito.

Ang isang task na IN_PROGRESS na ay hindi maaaring i-delete: ang request ay tatanggihan na may 409 Conflict at magpapatuloy pa rin ang pagtakbo ng task. Ang mga credits para sa isang task na nasimulan na ng worker ay hindi na maaaring i-refund, kaya kung ide-delete ito habang tumatakbo ay mawawala sa iyo ang credits pati na rin ang resulta. Hintayin na umabot ito sa SUCCEEDED, FAILED o CANCELED, bago ito i-delete.

Ang isang task na nasa terminal state (SUCCEEDED, FAILED o CANCELED) ay made-delete nang walang refund.

Ibinabalik

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

Request

DELETE

/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-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/text-to-image

List Text to Image Tasks

Ang endpoint na ito ay nagbibigay-daan sa iyo upang kunin ang isang listahan ng mga Text 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. Ang pinakamataas na pinapayagan ay 100 na item.
Name
sort_by
Type
string
Description
Field na gagamitin sa pag-uuri. Mga magagamit na halaga:
- +created_at: Isaayos ayon sa oras ng paggawa nang pataas (ascending order).
- -created_at: Isaayos ayon sa oras ng paggawa nang pababa (descending order).

Ibinabalik

Nagbabalik ng isang pinaginang (paginated) listahan ng The Text to Image Task Objects.

Request

GET

/openapi/v1/text-to-image

curl https://api.meshy.ai/openapi/v1/text-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-image",
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "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/text-to-image/:id/stream

I-stream ang Text to Image Task

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

Mga Parameter

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

Ibinabalik

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

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

Request

GET

/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/text-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": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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 Text to Image Task Object

Ang Text to Image Task object ay isang work unit na sinusubaybayan ng Meshy upang bumuo ng larawan mula sa 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 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 Text to Image tasks, ito ay laging magiging text-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-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 buuin ang larawan.
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 timestamp ay kumakatawan sa bilang ng mga milliseconds na lumipas mula Enero 1, 1970 UTC, kasunod ng 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 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 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 larawan. 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 buong reference ng task_error object.
Name
consumed_credits
Type
integer
Description
Ang bilang ng 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 na task (ang credits ay nire-refund kapag nabigo).

Example Text to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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
}