Text to Image API

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

POST/openapi/v1/text-to-image

Gumawa ng Text to Image Task

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

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-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 model (9 credits bawat imahe)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), isang high-fidelity na image model (9 credits bawat imahe)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), isang high-fidelity na image model (9 credits bawat imahe)
Name
prompt
Type
string
Kinakailangan
Description
Isang paglalarawang teksto ng imaheng nais mong buuin. Maging detalyado para sa pinakamahusay na resulta.
Name
generate_multi_view
Type
boolean
default false
Description
Kapag nakatakda sa true, gumagawa ito ng multi-view na imahe na nagpapakita ng subject mula sa iba't ibang anggulo.
Kapag true ang generate_multi_view, hindi maaaring itakda ang parameter na aspect_ratio.
Name
pose_mode
Type
string
Description
Tukuyin ang pose_mode para sa paggawa ng character. Kapag hindi ito isinama, ang imahe ay bubuuin nang walang anumang pose presets.
Mga available na value: a-pose, t-pose
Name
aspect_ratio
Type
string
default 1:1
Description
Tukuyin ang aspect ratio ng imaheng bubuuin. 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 na landscape
- 9:16: Widescreen na portrait
- 4:3: Standard na landscape
- 3:4: Standard na portrait
- 3:2: Landscape (suportado lamang ng mga GPT Image na modelo)
- 2:3: Portrait (suportado lamang ng mga GPT Image na modelo)
Name
remove_background
Type
boolean
default false
Description
Kapag nakatakda sa true, ang bubuuing imahe ay ibabalik bilang transparent na RGBA PNG na may tinanggal na background, para maaari mong i-composite ang subject sa anumang background.

Mga Ibinabalik

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

Mga Paraan ng Pagkabigo

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Karaniwang mga sanhi:
- Nawawalang parameter: Nawawala ang isang kinakailangang parameter (hal., ai_model, prompt).
- Di-wastong parameter: Ang ai_model o aspect_ratio ay hindi isa sa mga pinapayagang value.
- Salungatan: Hindi maaaring gamitin nang 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
Hindi sapat ang credits upang isagawa ang task na ito.
Name
429 - Too Many Requests
Description
Nalagpasan mo na ang 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

Kunin ang isang Text to Image Task

Ang endpoint na ito ay nagbibigay-daan sa iyo na kunin ang isang Text to Image task gamit ang isang valid na task id. Sumangguni sa The Text to Image Task Object upang makita kung aling mga properties 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

Burahin ang Text to Image Task

Permanenteng binubura ng endpoint na ito ang isang Text to Image task, kasama ang lahat ng kaugnay na larawan at data. Hindi na maibabalik ang aksyong ito.

Mga Path Parameter

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

Katayuan ng Task

Ang task na PENDING pa ay buburahin at ang credits na nagamit noong paglikha nito ay ire-refund.

Ang task na IN_PROGRESS na ay hindi na maaaring burahin: tatanggihan ang request na may 409 Conflict at ang task ay patuloy na tatakbo. Ang credits para sa task na sinimulan na ng worker ay hindi na maaaring i-refund, kaya ang pagbura dito habang tumatakbo ay magiging lugi ka sa credits at sa resulta. Hintayin muna itong umabot sa SUCCEEDED, FAILED o CANCELED, bago ito burahin.

Ang task na nasa terminal state (SUCCEEDED, FAILED o CANCELED) ay buburahin 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 na kunin ang isang listahan ng mga Text to Image task.

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-sort. Mga available na value:
- +created_at: I-sort ayon sa oras ng paglikha nang pataas (ascending).
- -created_at: I-sort ayon sa oras ng paglikha nang pababa (descending).

Ibinabalik

Nagbabalik ng isang naka-pagination na 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 isang Text to Image Task

Ang endpoint na ito ay nag-i-stream ng real-time na mga update 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 isasama lamang ang mga kinakailangang field na progress at status.

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 yunit ng trabaho na sinusubaybayan ni Meshy upang bumuo ng imahe mula sa isang text prompt na input. Ang object ay may mga sumusunod na katangian:

Mga Katangian

Name
id
Type
string
Description
Natatanging identifier para sa gawain. 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 Text to Image task, palagi itong magiging text-to-image.
Name
ai_model
Type
string
Description
Ang AI model na ginamit para sa gawaing 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 bumuo ng imahe.
Name
status
Type
string
Description
Status ng gawain. Ang posibleng mga value ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress ng gawain. Kung hindi pa nagsisimula ang gawain, ang property na ito ay magiging 0. Kapag nagtagumpay na ang gawain, ito ay magiging 100.
Name
created_at
Type
timestamp
Description
Timestamp kung kailan nilikha ang gawain, sa milliseconds.
Ang timestamp ay kumakatawan sa bilang ng milliseconds na lumipas mula 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 gawain, sa milliseconds. Kung hindi pa nagsisimula ang gawain, ang property na ito ay magiging 0.
Name
finished_at
Type
timestamp
Description
Timestamp kung kailan natapos ang gawain, sa milliseconds. Kung hindi pa natatapos ang gawain, ang property na ito ay magiging 0.
Name
expires_at
Type
timestamp
Description
Timestamp kung kailan mag-e-expire ang resulta ng gawain, sa milliseconds.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga naunang gawain.
Ang value ng field na ito ay makabuluhan lamang kung ang status ng gawain ay PENDING.
Name
image_urls
Type
array
Description
Isang array ng mga na-download na URL patungo sa mga nabuong imahe. Kapag pinagana ang generate_multi_view, ang array na ito ay naglalaman ng tatlong image URL na kumakatawan sa iba't ibang anggulo ng pagtingin. Kung hindi, iisang image URL lamang ang laman nito.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga nabigong gawain. Tingnan ang Errors para sa buong reference ng task_error object.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na nagamit ng gawaing ito. Naroroon kapag ang status ng gawain ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED na gawain (ang credits ay ire-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
}