Text to Image API

Gumawa ng mga larawan mula sa isang text prompt gamit ang mga AI model ng Meshy.

Ang Text to Image ay gumagawa ng mga larawan. Para gumawa ng 3D model ng nasa isang larawan, gamitin ang Image to 3D. Para gumawa ng 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 isang keychain, fridge magnet, figure, lampara, o keycap.

POST/openapi/v1/text-to-image

Gumawa ng Text to Image task

Gumagawa ng Text to Image task. Tumatakbo ang task sa background. Para malaman kung gaano karaming oras karaniwang tumatagal ang isang task, tingnan ang Processing times.

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

Mga Parameter

Name
ai_model
Type
string
Kinakailangan
Description
Ang AI model na gumagawa ng larawan. Nagkakaiba ang presyo depende sa model. Para sa presyo, tingnan ang Pricing.
Mga available na value:
- nano-banana: ang standard na model
- nano-banana-2: mas may kakayahan kaysa 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 model, na may mas mataas na kalidad. Nangangailangan ng Pro plan o mas mataas. 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 larawang gagawin. Mas magandang resulta ang ibinibigay ng detalyadong paglalarawan.
Name
generate_multi_view
Type
boolean
default false
Description
Kung gagawa ng multi-view na larawan na nagpapakita ng subject mula sa iba't ibang anggulo. Kapag true ito, hindi mo maaaring ipadala ang aspect_ratio. Kapag parehong ipinadala, nagbabalik ito ng 400.
Name
pose_mode
Type
string
Description
Ang pose para sa isang character, a-pose o t-pose. Iwanang blangko kung walang pose.
Ang paggana ng pose ay depende sa ai_model:
- nano-banana-2, nano-banana-2-lite, at nano-banana-2-1: Pinananatili ng Meshy ang model na pinili mo. Laging 3:4 ang larawan, at hindi pinapansin ng Meshy ang aspect_ratio.
- nano-banana at nano-banana-pro: Ginagawa ng Meshy ang larawan gamit ang nano-banana-pro, kaya ang ai_model ng task ay magbabalik bilang nano-banana-pro. Nangangailangan ito ng Pro plan o mas mataas. Laging 3:4 ang larawan, at hindi pinapansin ng Meshy ang aspect_ratio.
- Ang mga GPT Image model (gpt-image-2, gpt-image-2-5-flare, at gpt-image-2-5-sunburst): Pinananatili ng Meshy ang model na pinili mo at ang iyong aspect_ratio.
Name
aspect_ratio
Type
string
default 1:1
Description
Ang hugis ng larawan. Ang mga value na maaari mong ipadala ay depende sa ai_model.
Mga available na value:
- 1:1: square
- 16:9: widescreen landscape
- 9:16: widescreen portrait
- 4:3: standard landscape
- 3:4: standard portrait
- 3:2: landscape, para lang sa mga GPT Image model
- 2:3: portrait, para lang sa mga GPT Image model
Nagbabalik ng 400 ang mga nano-banana model (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1, at nano-banana-pro) para sa 3:2 at 2:3.
Name
remove_background
Type
boolean
default false
Description
Kung aalisin ang background ng larawan. Nagbabalik ang true ng transparent na RGBA PNG, para maaari mong ilagay ang subject sa anumang background.

Mga Ibinabalik

Ang result field ng response ay naglalaman ng ID ng bagong Text to Image task.

Mga mode ng kabiguan

Name
400 - Bad Request
Description
Hindi maaaring tumakbo ang request. Sinasabi ng error message kung aling problema ang nahanap nito. Halimbawa:
- Nawawalang parameter: May nawawalang required na parameter, tulad ng ai_model o prompt.
- Invalid na parameter: Hindi isa sa mga pinapayagang value ang ai_model o aspect_ratio.
- Salungatan: Ipinadala ang aspect_ratio kasama ang generate_multi_view: true.
Ayusin ang request, pagkatapos ay ipadala itong muli. Tingnan ang Errors.
Name
401 - Unauthorized
Description
Nawawala o hindi valid ang API key. Suriin ang Authorization header.
Name
402 - Payment Required
Description
Hindi maaaring patakbuhin ng account ang task na ito. Halimbawa:
- Free plan: Nangangailangan ng paid plan ang paggawa ng task. I-upgrade ang iyong plan sa iyong subscription settings, pagkatapos ay subukan ulit.
- Hindi sapat na credits: Walang sapat na credits ang account para sa task na ito (Insufficient funds), o naabot na ng account ang credit limit.
- Kailangan ng plan: Ginagamit ng request ang nano-banana-pro, o pose_mode kasama ang nano-banana, sa isang plan na mas mababa sa Pro (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)).
Suriin ang iyong credit balanse at plan, pagkatapos ay subukan ulit.
Name
429 - Too Many Requests
Description
Nalagpasan mo ang iyong rate limit. Maghintay, pagkatapos ay subukan ulit. Tingnan ang Rate limits.

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

Kumuha ng Text to Image task

Ibinabalik ang isang Text to Image task gamit ang kanyang ID.

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

Mga Parameter

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

Ibinabalik

Ang Text to Image task object.

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

Mag-delete ng Text to Image task

Permanenteng nagde-delete ng isang Text to Image task, kasama na ang mga larawan at data nito. Hindi mo na maaaring i-undo ang pag-delete.

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 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 ide-delete.

Status ng task

Kapag nag-delete ka ng PENDING na task, maire-refund ang mga credits na nagamit noong ginawa mo ito.

Hindi maaaring i-delete ang isang IN_PROGRESS na task. Magbabalik ang request ng 409 Conflict, at patuloy na tatakbo ang task. Hindi nire-refund ni Meshy ang isang task na nasimulan na, kaya kung ide-delete mo ito, mawawalan ka ng credits at ng resulta. Hintayin munang umabot ito sa SUCCEEDED, FAILED, o CANCELED, bago ito i-delete.

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

Mga ibinabalik

200 OK kapag na-delete na ang task, o 409 Conflict kapag ang task ay IN_PROGRESS.

GET/openapi/v1/text-to-image

I-list ang mga Text to Image na gawain

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

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

Mga Parameter

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

Mga Ibinabalik

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

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

I-stream ang isang Text to Image na gawain

Nag-i-stream ng mga update ng isang Text to Image na gawain bilang Server-Sent Events (SSE).

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

Mga Parameter

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

Ibinabalik

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

Ang bawat event ay naglalaman ng kumpletong task object, sa parehong anyo na ibinabalik ng Get endpoint. Habang ang gawain ay PENDING o IN_PROGRESS, ang mga resulta nitong field ay wala pang mga value.

Ang Text to Image task object

Inilalarawan ng isang Text to Image task object ang isang pagbuo ng larawan mula sa isang text prompt. Nilalaman nito ang status, ang progress, at ang mga image URL kapag nagtagumpay ang task.

Mga Katangian

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,
  "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 na string, at huwag umasa sa format nito.
Name
type
Type
string
Description
Ang uri ng task, palaging text-to-image.
Name
ai_model
Type
string
Description
Ang AI model na ginamit ng task.
Mga posibleng value:
- 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 ginamit mo noong ginawa ang task.
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 na katapos ang task, bilang isang porsyento. Ito ay 0 hanggang magsimula ang task at 100 kapag ito ay nagtagumpay.
Name
created_at
Type
timestamp
Description
Oras na nilikha ang task, sa Unix milliseconds.
Name
started_at
Type
timestamp
Description
Oras na nagsimula ang task, sa Unix milliseconds. Wala hangga't hindi pa nagsisimula ang task.
Name
finished_at
Type
timestamp
Description
Oras na natapos ang task, sa Unix milliseconds. Wala hangga't hindi pa natatapos ang task.
Name
expires_at
Type
timestamp
Description
Oras na mag-e-expire ang mga resulta ng task, sa Unix milliseconds. Wala hangga't hindi pa natatapos ang task.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga task na nauuna sa task na ito sa queue. Makabuluhan lamang ang value habang ang task ay PENDING. Hindi isinasama ang field kapag ang value ay 0.
Name
image_urls
Type
array
Description
Mga download URL para sa mga nabuong larawan. Gamit ang generate_multi_view: true, nilalaman ng array ang isang URL bawat view, karaniwang tatlo. Kung hindi mahiwalay ni Meshy ang bawat view, mas kaunti ang ibinabalik nito, at magtatagumpay pa rin ang task. Kung hindi, isang URL lamang ang nilalaman 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 mga 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 ni Meshy ang mga credits kapag nabigo ang isang task.