Text to Image API

Generate images from a text prompt with Meshy's AI models.

Text to Image makes images. To make a 3D model of what's in an image, use Image to 3D. To make an object you can hold or print from a photo, use the Creative Lab APIs. They make a prototype image and then build a 3D model from it, for example a keychain, fridge magnet, figure, lamp, or keycap.

POST/openapi/v1/text-to-image

Create a Text to Image task

Creates a Text to Image task. The task runs in the background. For how long a task usually takes, see 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"
}

Parameters

Name
ai_model
Type
string
Required
Description
The AI model that generates the image. Prices differ by model. For prices, see Pricing.
Available values:
- nano-banana: the standard model
- nano-banana-2: more capable than nano-banana
- nano-banana-2-lite: a lite version of nano-banana-2
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: the Pro model, with higher quality. Needs a Pro plan or higher. On a lower plan, it returns 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
Required
Description
Text that describes the image to generate. A detailed description gives better results.
Name
generate_multi_view
Type
boolean
default false
Description
Whether to generate a multi-view image that shows the subject from several angles. When it's true, you can't send aspect_ratio. Sending both returns 400.
Name
pose_mode
Type
string
Description
The pose for a character, a-pose or t-pose. Leave it out for no pose.
How a pose works depends on ai_model:
- nano-banana-2, nano-banana-2-lite, and nano-banana-2-1: Meshy keeps the model you chose. The image is always 3:4, and Meshy ignores aspect_ratio.
- nano-banana and nano-banana-pro: Meshy generates the image with nano-banana-pro, so the task's ai_model reads back as nano-banana-pro. This needs a Pro plan or higher. The image is always 3:4, and Meshy ignores aspect_ratio.
- The GPT Image models (gpt-image-2, gpt-image-2-5-flare, and gpt-image-2-5-sunburst): Meshy keeps the model you chose and your aspect_ratio.
Name
aspect_ratio
Type
string
default 1:1
Description
The shape of the image. The values you can send depend on ai_model.
Available values:
- 1:1: square
- 16:9: widescreen landscape
- 9:16: widescreen portrait
- 4:3: standard landscape
- 3:4: standard portrait
- 3:2: landscape, GPT Image models only
- 2:3: portrait, GPT Image models only
The nano-banana models (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1, and nano-banana-pro) return 400 for 3:2 and 2:3.
Name
remove_background
Type
boolean
default false
Description
Whether to remove the image's background. true returns a transparent RGBA PNG, so you can place the subject on any background.

Returns

The result field of the response holds the ID of the new Text to Image task.

Failure modes

Name
400 - Bad Request
Description
The request can't run. The error message says which problem it found. For example:
- Missing parameter: A required parameter, such as ai_model or prompt, is missing.
- Invalid parameter: ai_model or aspect_ratio isn't one of the allowed values.
- Conflict: aspect_ratio was sent with generate_multi_view: true.
Fix the request, then send it again. See Errors.
Name
401 - Unauthorized
Description
The API key is missing or invalid. Check the Authorization header.
Name
402 - Payment Required
Description
The account can't run this task. For example:
- Free plan: Creating a task requires a paid plan. Upgrade your plan in your subscription settings, then retry.
- Insufficient credits: The account doesn't have enough credits for this task (Insufficient funds), or the account reached a credit limit.
- Plan required: The request uses nano-banana-pro, or pose_mode with nano-banana, on a plan below Pro (Only Pro and above users can use nano-banana-pro, or Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).
Check your credit balance and plan, then retry.
Name
429 - Too Many Requests
Description
You exceeded your rate limit. Wait, then retry. See Rate limits.

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

Get a Text to Image task

Returns a Text to Image task by its 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=***"
  ]
}

Parameters

Name
id
Type
path
Description
The task ID from the create response.

Returns

The Text to Image task object.

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

Delete a Text to Image task

Permanently deletes a Text to Image task, including its images and data. You can't undo a 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."
}

Path parameters

Name
id
Type
path
Description
The ID of the task to delete.

Task status

Deleting a PENDING task refunds the credits it used when you created it.

An IN_PROGRESS task can't be deleted. The request returns 409 Conflict, and the task keeps running. Meshy doesn't refund a task that has started, so deleting it would cost you both the credits and the result. Wait for it to reach SUCCEEDED, FAILED, or CANCELED, then delete it.

Deleting a task in a final status (SUCCEEDED, FAILED, or CANCELED) doesn't refund its credits.

Returns

200 OK when the task is deleted, or 409 Conflict when the task is IN_PROGRESS.

GET/openapi/v1/text-to-image

List Text to Image tasks

Returns a list of your Text to Image and Image to Image tasks. Each task's type field says which of the two it is.

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

Parameters

Name
page_num
Type
integer
Description
The page number to return. Starts at and defaults to 1.
Name
page_size
Type
integer
Description
The number of tasks per page, up to 100. Defaults to 10.
Name
sort_by
Type
string
Description
The sort order.
Available values:
- +created_at: oldest first
- -created_at: newest first

Returns

A paginated list of task objects, in the same format as the Text to Image task object.

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

Stream a Text to Image task

Streams a Text to Image task's updates as 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=***"
  ]
}

Parameters

Name
id
Type
path
Description
The task ID from the create response.

Returns

A stream of Text to Image task objects as Server-Sent Events.

Each event holds the full task object, in the same shape the Get endpoint returns. While the task is PENDING or IN_PROGRESS, its result fields don't have values yet.

The Text to Image task object

A Text to Image task object describes one image generation from a text prompt. It holds the status, the progress, and the image URLs when the task succeeds.

Properties

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
The task ID. Treat it as an opaque string, and don't rely on its format.
Name
type
Type
string
Description
The task type, always text-to-image.
Name
ai_model
Type
string
Description
The AI model the task used.
Possible values:
- 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
The text prompt you created the task with.
Name
status
Type
string
Description
The task status, one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, or CANCELED.
Name
progress
Type
integer
Description
How much of the task is done, as a percentage. It's 0 until the task starts and 100 when it succeeds.
Name
created_at
Type
timestamp
Description
Time the task was created, in Unix milliseconds.
Name
started_at
Type
timestamp
Description
Time the task started, in Unix milliseconds. Absent until the task starts.
Name
finished_at
Type
timestamp
Description
Time the task finished, in Unix milliseconds. Absent until the task finishes.
Name
expires_at
Type
timestamp
Description
Time the task's results expire, in Unix milliseconds. Absent until the task finishes.
Name
preceding_tasks
Type
integer
Description
The number of tasks ahead of this one in the queue. The value is meaningful only while the task is PENDING. The field is left out when the value is 0.
Name
image_urls
Type
array
Description
Download URLs for the generated images. With generate_multi_view: true, the array holds one URL per view, usually three. If Meshy can't separate every view, it returns fewer, and the task still succeeds. Otherwise, it holds one URL.
Name
task_error
Type
object
Description
The error details when the task fails. It's null unless the status is FAILED. See Errors.
Name
consumed_credits
Type
integer
Description
The number of credits the task used. Present when the status is PENDING, IN_PROGRESS, or SUCCEEDED. It's 0 for a FAILED task, because Meshy refunds the credits when a task fails.