Text to Image API

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

POST/openapi/v1/text-to-image

Gumawa ng Text to Image Task

Pinapayagan ka ng endpoint na ito na gumawa ng bagong Text to Image task. Sumangguni sa Ang Text to Image Task Object para makita kung aling mga property ang kasama sa Text to Image task object.

Mga parameter

Name
ai_model
Type
string
Kinakailangan
Description
ID ng model na gagamitin para sa pagbuo ng larawan.
Mga available na value:
- nano-banana: Standard na model (3 credits bawat larawan)
- nano-banana-2: Balanseng model na may mas malakas na kakayahan kaysa standard (6 credits bawat larawan)
- nano-banana-pro: Pro model na may pinahusay na kalidad (9 credits bawat larawan)
- gpt-image-2: OpenAI GPT Image 2, isang high-fidelity na image model na may limitadong suporta sa aspect-ratio (9 credits bawat larawan)
Name
prompt
Type
string
Kinakailangan
Description
Isang tekstong paglalarawan ng larawang gusto mong buuin. Maging deskriptibo para sa pinakamagandang resulta.
Name
generate_multi_view
Type
boolean
default false
Description
Kapag nakatakda sa true, bumubuo ng multi-view na larawan na ipinapakita ang subject mula sa maraming anggulo.
Kapag ang generate_multi_view ay true, hindi maaaring itakda ang aspect_ratio parameter.
Name
pose_mode
Type
string
Description
Tukuyin ang pose mode para sa pagbuo ng character. Kapag hindi inilagay, bubuuin ang larawan nang walang anumang pose preset.
Mga available na value: a-pose, t-pose
Name
aspect_ratio
Type
string
default 1:1
Description
Tukuyin ang aspect ratio ng nabuong larawan. Nakadepende ang mga pinapayagang value 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: 1:1, 3:2, 2:3 lamang
Mga available na value:
- 1:1: Square na format
- 16:9: Widescreen landscape (hindi sinusuportahan ng gpt-image-2)
- 9:16: Widescreen portrait (hindi sinusuportahan ng gpt-image-2)
- 4:3: Standard landscape (hindi sinusuportahan ng gpt-image-2)
- 3:4: Standard portrait (hindi sinusuportahan ng gpt-image-2)
- 3:2: Landscape (sinusuportahan lamang ng gpt-image-2)
- 2:3: Portrait (sinusuportahan lamang ng gpt-image-2)

Nagbabalik

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

Mga Failure Mode

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Mga karaniwang sanhi:
- Nawawalang parameter: Nawawala ang isang kinakailangang parameter (hal., ai_model, prompt).
- Invalid na parameter: Ang ai_model o aspect_ratio ay hindi isa sa mga pinapayagang value.
- Conflict: 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 para isagawa ang task na ito.
Name
429 - Too Many Requests
Description
Lumampas ka na 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

Kunin ang isang Text to Image Task

Pinapayagan ka ng endpoint na ito na kunin ang isang Text to Image task gamit ang valid na task id. Sumangguni sa Ang Text to Image Task Object para makita kung aling 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.

Mga Ibinabalik

Naglalaman ang response ng Text to Image task object. Tingnan ang seksyong Ang Text to Image Task Object 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

Tanggalin ang isang Text to Image Task

Permanenteng dine-delete ng endpoint na ito ang isang Text to Image task, kabilang ang lahat ng kaugnay na larawan at data. Hindi na mababawi ang aksyong ito.

Mga Path Parameter

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

Ibinabalik

Ibinabalik ang 200 OK kapag matagumpay.

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

// Returns 200 Ok on success.

GET/openapi/v1/text-to-image

Listahan ng mga Text to Image Task

Pinapayagan ka ng endpoint na ito na kunin ang listahan ng mga Text to Image task.

Mga Parameter

Name
page_num
Type
integer
Description
Numero ng pahina para sa pagination. Nagsisimula at naka-default sa 1.
Name
page_size
Type
integer
Description
Limitasyon sa laki ng pahina. Naka-default sa 10 item. Ang pinakamataas na pinapayagan ay 50 item.
Name
sort_by
Type
string
Description
Field na pagbabasehan ng pag-sort. Mga available na value:
- +created_at: I-sort ayon sa oras ng paggawa sa pataas na pagkakasunod-sunod.
- -created_at: I-sort ayon sa oras ng paggawa sa pababang pagkakasunod-sunod.

Mga Ibinabalik

Nagbabalik ng listahang may pagination ng mga Text to Image Task Object.

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

Mag-stream ng isang Text to Image Task

Ang endpoint na ito ay nag-stream ng mga real-time na 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.

Mga Ibinabalik

Nagbabalik ng stream ng Mga Text to Image Task Object bilang Server-Sent Events.

Para sa mga task na PENDING o IN_PROGRESS, isasama lang ng response stream 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 work unit na sinusubaybayan ng Meshy upang makabuo ng image mula sa text prompt na input. May mga sumusunod na property ang object:

Mga Property

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 pagpapalagay tungkol sa format ng id.
Name
type
Type
string
Description
Ang uri ng task sa pagbuo ng larawan. Para sa mga task na Text to Image, palagi itong magiging text-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-pro, o gpt-image-2.
Name
prompt
Type
string
Description
Ang text prompt na ginamit upang buuin ang larawan.
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 nagtagumpay na ang task, magiging 100 ito.
Name
created_at
Type
timestamp
Description
timestamp kung kailan ginawa ang task, sa milliseconds.
Ang timestamp ay kumakatawan sa bilang ng milliseconds 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. Nalalapat ito 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 tapos 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.
Makabuluhan lamang ang value ng field na ito kung ang status ng task ay PENDING.
Name
image_urls
Type
array
Description
Isang array ng nada-download na mga URL patungo sa mga nabuong larawan. Kapag naka-enable ang generate_multi_view, naglalaman ang array na ito ng tatlong image URL na kumakatawan sa iba't ibang anggulo ng pagtingin. Kung hindi, naglalaman ito ng isang image URL.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa buong task_error object reference.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na nakonsumo ng task na ito. Naroroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga task na FAILED (ibinabalik ang credits 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
}