> **Reading as an AI agent?** This is the Markdown version of https://docs.meshy.ai/api/text-to-image.
>
> - Full docs index: https://docs.meshy.ai/llms.txt
> - Single-fetch full content: https://docs.meshy.ai/llms-full.txt
> - Tool-calling access via MCP server: https://docs.meshy.ai/api/ai

---
# Text to Image API

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

> **Note:** Text to Image makes **images**. To make a 3D model of what's in an image, use [Image to 3D](/api/image-to-3d). To make an object you can hold or print from a photo, use the [Creative Lab APIs](/api/creative-lab-keychain). 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](/api/task-lifecycle#processing-times).

### Parameters

  - `ai_model` · *string* · **required**

  The AI model that generates the image. Prices differ by model. For prices, see [Pricing](/api/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)

  - `prompt` · *string* · **required**

  Text that describes the image to generate. A detailed description gives better results.

  - `generate_multi_view` · *boolean* · default: `false`

  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`.

  - `pose_mode` · *string*

  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`.

  - `aspect_ratio` · *string* · default: `1:1`

  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`.

  - `remove_background` · *boolean* · default: `false`

  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

  - `400 - Bad Request`

  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](/api/errors#request-errors).

  - `401 - Unauthorized`

  The API key is missing or invalid. Check the `Authorization` header.

  - `402 - Payment Required`

  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](https://www.meshy.ai/settings/subscription), 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.

  - `429 - Too Many Requests`

  You exceeded your rate limit. Wait, then retry. See [Rate limits](/api/rate-limits).

**cURL**

```bash
# 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"
  }'
```

```javascript
import axios from 'axios'

// Generate an image from a text prompt
const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };
const payload = {
  ai_model: "nano-banana",
  prompt: "A majestic dragon soaring through clouds at sunset",
  aspect_ratio: "16:9"
};

try {
  const response = await axios.post(
    'https://api.meshy.ai/openapi/v1/text-to-image',
    payload,
    { headers }
  );
  console.log(response.data);
} catch (error) {
  console.error(error);
}
```

```python
import requests

# Generate an image from a text prompt
payload = {
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
}
headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
}

response = requests.post(
    "https://api.meshy.ai/openapi/v1/text-to-image",
    headers=headers,
    json=payload,
)
response.raise_for_status()
print(response.json())
```

**Response**

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

---

## GET /openapi/v1/text-to-image/:id -- Get a Text to Image task

Returns a Text to Image task by its ID.

### Parameters

  - `id` · *path*

  The task ID from the create response.

### Returns

The [Text to Image task object](#the-text-to-image-task-object).

**cURL**

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

```javascript
import axios from 'axios'

const taskId = '018a210d-8ba4-705c-b111-1f1776f7f578';
const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };

try {
  const response = await axios.get(
    `https://api.meshy.ai/openapi/v1/text-to-image/${taskId}`,
    { headers }
  );
  console.log(response.data);
} catch (error) {
  console.error(error);
}
```

```python
import requests

task_id = "018a210d-8ba4-705c-b111-1f1776f7f578"
headers = {
    "Authorization": f"Bearer {YOUR_API_KEY}"
}

response = requests.get(
    f"https://api.meshy.ai/openapi/v1/text-to-image/{task_id}",
    headers=headers,
)
response.raise_for_status()
print(response.json())
```

**Response**

```json
{
  "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 -- Delete a Text to Image task

Permanently deletes a Text to Image task, including its images and data. You can't undo a delete.

### Path parameters

  - `id` · *path*

  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`.

  **cURL**

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

  ```javascript
  import axios from 'axios'

  const taskId = '018a210d-8ba4-705c-b111-1f1776f7f578'
  const headers = { Authorization: `Bearer ${YOUR_API_KEY}` }

  try {
    await axios.delete(
      `https://api.meshy.ai/openapi/v1/text-to-image/${taskId}`,
      { headers }
    )
  } catch (error) {
    console.error(error)
  }
  ```

  ```python
  import requests

  task_id = "018a210d-8ba4-705c-b111-1f1776f7f578"
  headers = {
      "Authorization": f"Bearer {YOUR_API_KEY}"
  }

  response = requests.delete(
      f"https://api.meshy.ai/openapi/v1/text-to-image/{task_id}",
      headers=headers,
  )
  response.raise_for_status()
  ```

**Response**

```json
// 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."
}
```

---

## 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.

### Parameters

  - `page_num` · *integer*

  The page number to return. Starts at and defaults to `1`.

  - `page_size` · *integer*

  The number of tasks per page, up to `100`. Defaults to `10`.

  - `sort_by` · *string*

  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](#the-text-to-image-task-object).

  **cURL**

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

  ```javascript
  import axios from 'axios'

  const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };

  try {
   const response = await axios.get(
     `https://api.meshy.ai/openapi/v1/text-to-image?page_size=10`,
  { headers }
    );
   console.log(response.data);
  } catch (error) {
   console.error(error);
  }
  ```

  ```python
  import requests

  headers = {
      "Authorization": f"Bearer {YOUR_API_KEY}"
  }

  response = requests.get(
      "https://api.meshy.ai/openapi/v1/text-to-image",
      headers=headers,
      params={"page_size": 10}
  )
  response.raise_for_status()
  print(response.json())
  ```

**Response**

```json
[
  {
    "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 -- Stream a Text to Image task

Streams a Text to Image task's updates as Server-Sent Events (SSE).

### Parameters

  - `id` · *path*

  The task ID from the create response.

### Returns

A stream of [Text to Image task objects](#the-text-to-image-task-object) 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.

  **cURL**

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

  ```javascript
  const response = await fetch(
    'https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream',
    {
      headers: { Authorization: `Bearer ${YOUR_API_KEY}` }
    }
  );

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop();

    for (const line of lines) {
      if (line.startsWith('data:')) {
        const data = JSON.parse(line.slice(5));
        console.log(data);

        if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(data.status)) {
          reader.cancel();
        }
      }
    }
  }
  ```

  ```python
  import requests
  import json

  headers = {
      "Authorization": f"Bearer {YOUR_API_KEY}",
      "Accept": "text/event-stream"
  }

  response = requests.get(
      'https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream',
      headers=headers,
      stream=True
  )

  for line in response.iter_lines():
      if line:
          if line.startswith(b'data:'):
              data = json.loads(line.decode('utf-8')[5:])
              print(data)

              if data['status'] in ['SUCCEEDED', 'FAILED', 'CANCELED']:
                  break

  response.close()
  ```

  **Response Stream**

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

---

## 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

- `id` · *string*

  The task ID. Treat it as an opaque string, and don't rely on its format.

- `type` · *string*

  The task type, always `text-to-image`.

- `ai_model` · *string*

  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`

- `prompt` · *string*

  The text prompt you created the task with.

- `status` · *string*

  The task status, one of `PENDING`, `IN_PROGRESS`, `SUCCEEDED`, `FAILED`, or `CANCELED`.

- `progress` · *integer*

  How much of the task is done, as a percentage. It's `0` until the task starts and `100` when it succeeds.

- `created_at` · *timestamp*

  Time the task was created, in Unix milliseconds.

- `started_at` · *timestamp*

  Time the task started, in Unix milliseconds. Absent until the task starts.

- `finished_at` · *timestamp*

  Time the task finished, in Unix milliseconds. Absent until the task finishes.

- `expires_at` · *timestamp*

  Time the task's results expire, in Unix milliseconds. Absent until the task finishes.

- `preceding_tasks` · *integer*

  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`.

- `image_urls` · *array*

  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.

- `task_error` · *object*

  The error details when the task fails. It's `null` unless the status is `FAILED`. See [Errors](/api/errors#task-errors).

- `consumed_credits` · *integer*

  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.

**Example Text to Image Task Object**

```json
{
  "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
}
```
