テキストから画像 API

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

POST/openapi/v1/text-to-image

Text to Image タスクを作成する

この endpoint では、新しい Text to Image タスクを作成できます。 Text to Image タスクオブジェクトに含まれるプロパティについては、 Text to Image タスクオブジェクトを参照してください。

パラメーター

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 クレジット）
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: 1:1, 3:2, 2:3 のみ
利用可能な値:
- 1:1: 正方形フォーマット
- 16:9: ワイドスクリーン横長（gpt-image-2 ではサポートされていません）
- 9:16: ワイドスクリーン縦長（gpt-image-2 ではサポートされていません）
- 4:3: 標準横長（gpt-image-2 ではサポートされていません）
- 3:4: 標準縦長（gpt-image-2 ではサポートされていません）
- 3:2: 横長（gpt-image-2 でのみサポート）
- 2:3: 縦長（gpt-image-2 でのみサポート）

戻り値

レスポンスの result プロパティには、新しく作成された Text to Image タスクのタスク id が含まれます。

失敗モード

Name
400 - Bad Request
Description
リクエストは受け付けられませんでした。一般的な原因:
- パラメーター不足: 必須パラメーター（例: ai_model, prompt）がありません。
- 無効なパラメーター: ai_model または aspect_ratio が許可された値のいずれでもありません。
- 競合: generate_multi_view と aspect_ratio は同時に使用できません。
Name
401 - Unauthorized
Description
認証に失敗しました。API key を確認してください。
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 タスクを取得

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

パラメータ

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

戻り値

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

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

Text to Image タスクを削除

この endpoint は、関連するすべての画像とデータを含め、Text to Image タスクを完全に削除します。この操作は元に戻せません。

パスパラメータ

Name
id
Type
path
Description
削除する Text to Image タスクの ID。

戻り値

成功時に 200 OK を返します。

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

テキストから画像タスクを一覧表示

この endpoint では、Text to Image タスクの一覧を取得できます。

パラメータ

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

戻り値

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

Text to Image タスクをストリーミングする

この endpoint は、Server-Sent Events (SSE) を使用して Text to Image タスクのリアルタイム更新をストリーミングします。

パラメータ

Name
id
Type
path
Description
ストリーミングする Text to Image タスクの一意の識別子。

戻り値

Server-Sent Events として Text to Image タスクオブジェクトのストリームを返します。

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

テキストから画像へのタスクオブジェクト

テキストから画像へのタスクオブジェクトは、テキストプロンプト入力から画像を生成するために Meshy が追跡する作業単位です。このオブジェクトには以下のプロパティがあります:

プロパティ

Name
id
Type
string
Description
タスクの一意の識別子です。実装の詳細として、タスク ID には k ソート可能な 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 です。
Name
prompt
Type
string
Description
画像の生成に使用されたテキストプロンプトです。
Name
status
Type
string
Description
タスクのステータスです。指定可能な値は PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED のいずれかです。
Name
progress
Type
integer
Description
タスクの進行状況です。タスクがまだ開始されていない場合、このプロパティは 0 になります。タスクが成功すると、これは 100 になります。
Name
created_at
Type
timestamp
Description
タスクが作成された時刻のタイムスタンプ（ミリ秒）です。
タイムスタンプは、1970 年 1 月 1 日 UTC から経過したミリ秒数を表し、 RFC 3339 標準に従います。たとえば、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
}