Text to Image API

Text to Image API is a feature that allows you to integrate Meshy's AI image generation capabilities into your own application. Generate high-quality images from text prompts using our powerful AI models.

POST/openapi/v1/text-to-image

Create a Text to Image Task

This endpoint allows you to create a new Text to Image task. Refer to The Text to Image Task Object to see which properties are included with Text to Image task object.

Parameters

  • Name
    ai_model
    Type
    string
    Required
    Description

    ID of the model to use for image generation.

    Available values:

    • nano-banana: Standard model (3 credits per image)
    • nano-banana-2: Balanced model with stronger capability than standard (6 credits per image)
    • nano-banana-pro: Pro model with enhanced quality (9 credits per image)
    • gpt-image-2: OpenAI GPT Image 2, a high-fidelity image model (9 credits per image)
    • gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), a high-fidelity image model (9 credits per image)
    • gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), a high-fidelity image model (9 credits per image)
  • Name
    prompt
    Type
    string
    Required
    Description

    A text description of the image you want to generate. Be descriptive for best results.

  • Name
    generate_multi_view
    Type
    boolean
    default false
    Description

    When set to true, generates a multi-view image showing the subject from multiple angles.

    When generate_multi_view is true, the aspect_ratio parameter cannot be set.

  • Name
    pose_mode
    Type
    string
    Description

    Specify the pose mode for character generation. When omitted, the image is generated without any pose presets.

    Available values: a-pose, t-pose

  • Name
    aspect_ratio
    Type
    string
    default 1:1
    Description

    Specify the aspect ratio of the generated image. Allowed values depend on the selected 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

    Available values:

    • 1:1: Square format
    • 16:9: Widescreen landscape
    • 9:16: Widescreen portrait
    • 4:3: Standard landscape
    • 3:4: Standard portrait
    • 3:2: Landscape (only supported by the GPT Image models)
    • 2:3: Portrait (only supported by the GPT Image models)
  • Name
    remove_background
    Type
    boolean
    default false
    Description

    When set to true, the generated image is returned as a transparent RGBA PNG with the background removed, so you can composite the subject onto any background.

Returns

The result property of the response contains the task id of the newly created Text to Image task.

Failure Modes

  • Name
    400 - Bad Request
    Description

    The request was unacceptable. Common causes:

    • Missing parameter: A required parameter (e.g., ai_model, prompt) is missing.
    • Invalid parameter: ai_model or aspect_ratio is not one of the allowed values.
    • Conflict: generate_multi_view and aspect_ratio cannot be used simultaneously.
  • Name
    401 - Unauthorized
    Description

    Authentication failed. Please check your API key.

  • Name
    402 - Payment Required
    Description

    Insufficient credits to perform this task.

  • Name
    429 - Too Many Requests
    Description

    You have exceeded your 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

Retrieve a Text to Image Task

This endpoint allows you to retrieve a Text to Image task given a valid task id. Refer to The Text to Image Task Object to see which properties are included with Text to Image task object.

Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the Text to Image task to retrieve.

Returns

The response contains the Text to Image task object. Check The Text to Image Task Object section for details.

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

Delete a Text to Image Task

This endpoint permanently deletes a Text to Image task, including all associated images and data. This action is irreversible.

Path Parameters

  • Name
    id
    Type
    path
    Description

    The ID of the Text to Image task to delete.

Task Status

A task that is still PENDING is deleted and the credits consumed at create-time are refunded.

A task that is already IN_PROGRESS cannot be deleted: the request is rejected with 409 Conflict and the task keeps running. Credits for a task the worker has already started are not refundable, so deleting it mid-run would cost you the credits and the result both. Wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it.

A task in a terminal state (SUCCEEDED, FAILED or CANCELED) is deleted without a refund.

Returns

Returns 200 OK on success, or 409 Conflict when the task is 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

This endpoint allows you to retrieve a list of Text to Image tasks.

Parameters

  • Name
    page_num
    Type
    integer
    Description

    Page number for pagination. Starts and defaults to 1.

  • Name
    page_size
    Type
    integer
    Description

    Page size limit. Defaults to 10 items. Maximum allowed is 100 items.

  • Name
    sort_by
    Type
    string
    Description

    Field to sort by. Available values:

    • +created_at: Sort by creation time in ascending order.
    • -created_at: Sort by creation time in descending order.

Returns

Returns a paginated list of 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

Stream a Text to Image Task

This endpoint streams real-time updates for a Text to Image task using Server-Sent Events (SSE).

Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the Text to Image task to stream.

Returns

Returns a stream of The Text to Image Task Objects as Server-Sent Events.

For PENDING or IN_PROGRESS tasks, the response stream will only include necessary progress and status fields.

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

The Text to Image Task Object

The Text to Image Task object is a work unit that Meshy keeps track of to generate an image from a text prompt input. The object has the following properties:

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the task. While we use a k-sortable UUID for task ids as the implementation detail, you should not make any assumptions about the format of the id.

  • Name
    type
    Type
    string
    Description

    The type of image generation task. For Text to Image tasks, this will always be text-to-image.

  • Name
    ai_model
    Type
    string
    Description

    The AI model used for this task. Possible values are nano-banana, nano-banana-2, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare, or gpt-image-2-5-sunburst.

  • Name
    prompt
    Type
    string
    Description

    The text prompt that was used to generate the image.

  • Name
    status
    Type
    string
    Description

    Status of the task. Possible values are one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress of the task. If the task is not started yet, this property will be 0. Once the task has succeeded, this will become 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp of when the task was created, in milliseconds.

    A timestamp represents the number of milliseconds elapsed since January 1, 1970 UTC, following the RFC 3339 standard. For example, Friday, September 1, 2023 12:00:00 PM GMT is represented as 1693569600000. This applies to all timestamps in Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Timestamp of when the task was started, in milliseconds. If the task is not started yet, this property will be 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Timestamp of when the task was finished, in milliseconds. If the task is not finished yet, this property will be 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Timestamp of when the task result expires, in milliseconds.

  • Name
    preceding_tasks
    Type
    integer
    Description

    The count of preceding tasks.

    The value of this field is meaningful only if the task status is PENDING.

  • Name
    image_urls
    Type
    array
    Description

    An array of downloadable URLs to the generated images. When generate_multi_view is enabled, this array contains three image URLs representing different viewing angles. Otherwise, it contains a single image URL.

  • Name
    task_error
    Type
    object
    Description

    Error details for failed tasks. See Errors for the full task_error object reference.

  • Name
    consumed_credits
    Type
    integer
    Description

    The number of credits consumed by this task. Present when the task status is PENDING, IN_PROGRESS, or SUCCEEDED. Returns 0 for FAILED tasks (credits are refunded on failure).

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
}