テキストから画像 API

テキストから画像 APIは、MeshyのAI画像生成機能を独自のアプリケーションに統合できる機能です。強力なAIモデルを使用して、テキストプロンプトから高品質な画像を生成します。

POST/openapi/v1/text-to-image

テキストから画像タスクを作成

このエンドポイントを使用すると、新しいテキストから画像タスクを作成できます。テキストから画像タスクオブジェクトに含まれるプロパティについては、The Text to Image Task Objectを参照してください。

パラメータ

Name
ai_model
Type
string
必須
Description
画像生成に使用するモデルのID。
利用可能な値:
- nano-banana: 標準モデル（1画像あたり3クレジット）
- nano-banana-2: 標準よりも強力なバランス型モデル（1画像あたり6クレジット）
- nano-banana-pro: 品質を強化したProモデル（1画像あたり9クレジット）
- gpt-image-2: OpenAI GPT Image 2、高精細な画像モデル（1画像あたり9クレジット）
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare)、高精細な画像モデル（1画像あたり9クレジット）
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst)、高精細な画像モデル（1画像あたり9クレジット）
Name
prompt
Type
string
必須
Description
生成したい画像のテキスト説明です。最良の結果を得るために、できるだけ具体的に記述してください。
Name
generate_multi_view
Type
boolean
デフォルト false
Description
true に設定すると、複数の角度から被写体を表示するマルチビュー画像を生成します。
generate_multi_view が true の場合、aspect_ratio パラメータは設定できません。
Name
pose_mode
Type
string
Description
キャラクター生成のポーズモードを指定します。省略した場合、ポーズプリセットなしで画像が生成されます。
利用可能な値: a-pose、t-pose
Name
aspect_ratio
Type
string
デフォルト 1:1
Description
生成する画像のアスペクト比を指定します。使用できる値は、選択した 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
利用可能な値:
- 1:1: 正方形フォーマット
- 16:9: ワイドスクリーン横向き
- 9:16: ワイドスクリーン縦向き
- 4:3: 標準横向き
- 3:4: 標準縦向き
- 3:2: 横向き（GPT Imageモデルのみサポート）
- 2:3: 縦向き（GPT Imageモデルのみサポート）
Name
remove_background
Type
boolean
デフォルト false
Description
true に設定すると、生成された画像は背景が削除された透明なRGBA PNGとして返されるため、被写体を任意の背景に合成できます。

戻り値

レスポンスの result プロパティには、新しく作成されたテキストから画像タスクのタスク id が含まれます。

失敗モード

Name
400 - Bad Request
Description
リクエストが受理できませんでした。よくある原因:
- パラメータの欠落: 必須パラメータ（例: ai_model、prompt）が欠落しています。
- 無効なパラメータ: ai_model または aspect_ratio が許可された値のいずれでもありません。
- 競合: generate_multi_view と aspect_ratio は同時に使用できません。
Name
401 - Unauthorized
Description
認証に失敗しました。APIキーを確認してください。
Name
402 - Payment Required
Description
このタスクを実行するためのクレジットが不足しています。
Name
429 - Too Many Requests
Description
レート制限を超えました。

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

Text to Image タスクの取得

このエンドポイントでは、有効なタスク id を指定して Text to Image タスクを取得できます。 Text to Image タスクオブジェクトに含まれるプロパティについては、The Text to Image Task Object を参照してください。

パラメータ

Name
id
Type
path
Description
取得する Text to Image タスクの一意の識別子。

返り値

レスポンスには Text to Image タスクオブジェクトが含まれます。詳細は The Text to Image Task Object セクションを確認してください。

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

テキストから画像タスクを削除

このエンドポイントは、関連するすべての画像とデータを含め、テキストから画像タスクを完全に削除します。この操作は元に戻せません。

パスパラメータ

Name
id
Type
path
Description
削除するテキストから画像タスクのID。

タスクステータス

まだ PENDING のタスクは削除され、作成時に消費されたクレジットは返金されます。

すでに IN_PROGRESS のタスクは削除できません。リクエストは 409 Conflict で拒否され、タスクはそのまま実行を続けます。ワーカーがすでに開始しているタスクのクレジットは返金対象外のため、実行途中で削除するとクレジットと結果の両方を失うことになります。SUCCEEDED、FAILED、または CANCELED になるまで待ってから削除してください。

終了状態（SUCCEEDED、FAILED、または CANCELED）にあるタスクは、返金なしで削除されます。

戻り値

成功時は 200 OK を返します。タスクが IN_PROGRESS の場合は 409 Conflict を返します。

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

テキストから画像タスクのリスト取得

このエンドポイントを使用すると、テキストから画像タスクのリストを取得できます。

パラメータ

Name
page_num
Type
integer
Description
ページネーション用のページ番号。1 から始まり、デフォルトは 1 です。
Name
page_size
Type
integer
Description
ページサイズの上限。デフォルトは 10 件です。最大で 100 件まで指定できます。
Name
sort_by
Type
string
Description
ソートに使用するフィールド。利用可能な値：
- +created_at: 作成時刻の昇順でソートします。
- -created_at: 作成時刻の降順でソートします。

戻り値

テキストから画像タスクオブジェクトのページネーションされたリストを返します。

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

テキストから画像タスクをストリーミングする

このエンドポイントは、Server-Sent Events (SSE) を使用してテキストから画像タスクのリアルタイム更新をストリーミングします。

パラメータ

Name
id
Type
path
Description
ストリーミングするテキストから画像タスクの一意の識別子です。

返り値

テキストから画像タスクオブジェクトのストリームを Server-Sent Events として返します。

PENDING または IN_PROGRESS のタスクの場合、レスポンスストリームには必要な progress および 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=***"
  ]
}

The Text to Image Task Object

Text to Image Task オブジェクトは、text prompt の入力から画像を生成するために Meshy が管理する作業単位です。このオブジェクトには以下のプロパティがあります。

プロパティ

Name
id
Type
string
Description
タスクの一意識別子。タスク ID の実装詳細としては k-sortable UUID を使用していますが、id の形式について何らかの前提を置くべきではありません。
Name
type
Type
string
Description
画像生成タスクの種類。Text to Image タスクの場合、これは常に text-to-image になります。
Name
ai_model
Type
string
Description
このタスクに使用された AI モデル。指定可能な値は nano-banana、nano-banana-2、nano-banana-pro、gpt-image-2、gpt-image-2-5-flare、または gpt-image-2-5-sunburst です。
Name
prompt
Type
string
Description
画像の生成に使用されたテキスト prompt。
Name
status
Type
string
Description
タスクのステータス。指定可能な値は PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED のいずれかです。
Name
progress
Type
integer
Description
タスクの progress。タスクがまだ開始されていない場合、このプロパティは 0 になります。タスクが成功すると 100 になります。
Name
created_at
Type
timestamp
Description
タスクが作成された時刻を示すタイムスタンプ（ミリ秒単位）。
タイムスタンプは、RFC 3339 標準に従って、1970年1月1日 UTC からの経過ミリ秒数を表します。たとえば、2023年9月1日金曜日 12:00:00 PM GMT は 1693569600000 と表されます。これは Meshy API におけるすべてのタイムスタンプに当てはまります。
Name
started_at
Type
timestamp
Description
タスクが開始された時刻を示すタイムスタンプ（ミリ秒単位）。タスクがまだ開始されていない場合、このプロパティは 0 になります。
Name
finished_at
Type
timestamp
Description
タスクが終了した時刻を示すタイムスタンプ（ミリ秒単位）。タスクがまだ終了していない場合、このプロパティは 0 になります。
Name
expires_at
Type
timestamp
Description
タスクの結果が失効する時刻を示すタイムスタンプ（ミリ秒単位）。
Name
preceding_tasks
Type
integer
Description
先行タスクの件数。
このフィールドの値は、タスクのステータスが PENDING の場合にのみ意味を持ちます。
Name
image_urls
Type
array
Description
生成された画像へのダウンロード可能な URL の配列。generate_multi_view が有効な場合、この配列には異なる視点を表す3つの画像 URL が含まれます。それ以外の場合は、単一の画像 URL が含まれます。
Name
task_error
Type
object
Description
失敗したタスクのエラー詳細。task_error オブジェクトの完全なリファレンスについては、エラーを参照してください。
Name
consumed_credits
Type
integer
Description
このタスクで消費されたクレジット数。タスクのステータスが PENDING、IN_PROGRESS、または SUCCEEDED の場合に存在します。FAILED タスクの場合は 0 を返します（失敗時にはクレジットが返還されます）。

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
}