テキストから3D API
自分のアプリケーションでテキストプロンプトから3Dモデルを生成します。
テキストから3Dは2つのステップで動作します。まず、preview タスク(mode: "preview")を作成して、テクスチャのない3Dメッシュを生成し、形状を確認できるようにします。次に、成功したプレビューのタスクIDを refine タスク(mode: "refine")に送信して、メッシュにテクスチャを付けます。どちらのステップも同じエンドポイントを使用します。
Text to 3DのプレビュータスクをCreate
テキストprompt からテクスチャなしの3Dメッシュ(ジオメトリのみ)を生成する、Text to 3Dのプレビュータスクを作成します。これは2段階ワークフローの最初のステップです。プレビューが成功したら、そのタスクIDをrefineタスクに送信してメッシュにテクスチャを適用します。Text to 3Dのrefineタスクを作成を参照してください。完全なレスポンススキーマについては、Text to 3Dタスクオブジェクトを参照してください。
タスクはバックグラウンドで実行されます。タスクに通常かかる時間については、処理時間を参照してください。
Request
# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "preview",
"prompt": "a monster mask"
}'
# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "preview",
"prompt": "a futuristic robot warrior",
"ai_model": "meshy-7.1",
"geometry_resolution": "4k",
"should_remesh": true,
"target_polycount": 100000,
"pose_mode": "a-pose",
"target_formats": ["glb"]
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
パラメータ
- Name
- mode
- Type
- string
- 必須
- Description
2段階ワークフローのステップ。プレビュータスクを作成するには
previewを送信します。
- Name
- prompt
- Type
- string
- 必須
- Description
生成するオブジェクトを説明するテキスト。最大800文字。これを超える場合は
400が返されます。
- Name
- model_type
- Type
- string
- デフォルト standard
- Description
生成する3Dメッシュの種類。
利用可能な値:
standard: 高精細な3Dメッシュsmart-topology: Smart Topologyメッシュ。ai_model(meshy-t2またはmeshy-t2.5)でモデルを選択します。
smart-topologyを使用すると、Meshyはshould_remeshとdecimation_modeを無視し、topology: triangleのみを受け付けます。
- Name
- ai_model
- Type
- string
- デフォルト latest
- Description
3Dモデルを生成するAIモデル。利用可能な値は
model_typeによって異なります。標準モデル(
model_type: standard):meshy-6-litemeshy-6meshy-7.1latest: Meshy 7.1meshy-7(非推奨): 代わりにmeshy-7.1を送信してください。2026年12月31日に廃止されます。
Smart Topologyモデル(
model_type: smart-topology):meshy-t2: よりクリーンなtopology、ネイティブに分離されたパーツ、三角形出力、target_polycountで設定する面数meshy-t2.5(デフォルト): ゲームアセット向けのシャープなディテール、三角形出力、target_polycountで設定する面数
ゲームキャラクターや3Dプリントなど、プロジェクトに合うモデルについては、モデルを参照してください。
- Name
- geometry_resolution
- Type
- string
- デフォルト standard
- Description
ジオメトリ生成パス。プレビュータスクにのみ適用されます。このパラメータを指定したrefineは
400を返します。利用可能な値:
standard2k: 2048³でUltraパスを実行4k: 4096³でUltraパスを実行し、より精細な表面ディテールを得られます
2kにはmeshy-7.1、latest、または非推奨のmeshy-7が必要です。4kにはmeshy-7.1またはlatestが必要です。他のモデルでは400が返されます。
- Name
- ultra_mode
- Type
- boolean
- ⚠ 非推奨
- デフォルト false
- Description
代わりに
geometry_resolutionを送信してください。ultra_mode: trueはgeometry_resolution: "2k"と同じです。
- Name
- should_remesh
- Type
- boolean
- デフォルト true (meshy-6-lite), false (other models)
- Description
生成後にモデルをリメッシュするかどうか。最高品質の3Dモデルを得るには
falseを送信してください。
should_remesh = true- Name
- topology
- Type
- string
- デフォルト triangle
- Description
リメッシュされたモデルの面の種類。
利用可能な値:
quad: クアッド優位のメッシュtriangle: 間引かれた三角形メッシュ
Smart Topologyの出力は三角形のみです。
ai_modelがmeshy-t2またはmeshy-t2.5の場合にquadを送信すると400が返されます。
- Name
- decimation_mode
- Type
- integer
- Description
レベル別の適応的な面数。設定すると、Meshyは
target_polycountを無視します。利用可能な値:
1: ultra2: high3: medium4: low
- Name
- target_polycount
- Type
- integer
- Description
目標とする面数。ジオメトリによっては、結果が目標値と異なる場合があります。これは次の2つの別個のケースに適用されます:
- リメッシュ:
standardモデルでshould_remesh: trueの場合。Meshyはメッシュをこの面数付近までリメッシュ(間引き)します。decimation_modeを設定した場合、Meshyはそれを使用しtarget_polycountを無視します。 - Smart Topology:
model_type: smart-topologyとai_model(meshy-t2またはmeshy-t2.5)の場合。Meshyはこの面数で直接モデルを生成します。リメッシュは実行されず、should_remeshも不要です。
次の表は各ケースの範囲とデフォルト値を示します:
ケース 範囲 デフォルト リメッシュ 100~30000030000meshy-t2100~150004000meshy-t2.5100~3000015000範囲外の値は
400を返します。ローポリのゲームアセットには、標準モデルをリメッシュするのではなく、Smart Topologyモデルを使用してください。モデルを参照してください。
- リメッシュ:
- Name
- symmetry_mode
- Type
- string
- ⚠ 非推奨
- デフォルト auto
- Description
指定しないでください。このパラメータは出力に影響しません。
利用可能な値:
off: 対称を無効にするauto: 入力ジオメトリに基づいて対称を適用するon: 生成時に対称を強制する
- Name
- pose_mode
- Type
- string
- Description
キャラクターモデルのポーズ。
a-poseまたはt-pose。ポーズなしにするには、pose_modeとis_a_t_poseの両方を指定しないでください。
- Name
- is_a_t_pose
- Type
- boolean
- ⚠ 非推奨
- デフォルト false
- Description
代わりに
pose_modeを送信してください。モデルをAポーズまたはTポーズで生成するかどうか。
- Name
- art_style
- Type
- string
- ⚠ 非推奨
- デフォルト realistic
- Description
指定しないでください。Meshyはこれを無視します。
- Name
- moderation
- Type
- boolean
- デフォルト false
- Description
生成前に
promptに有害なコンテンツが含まれていないか確認するかどうか。Meshyが有害なコンテンツを検出した場合、リクエストは400を返し、Meshyはタスクを作成しません。
- Name
- target_formats
- Type
- string[]
- Description
生成するファイル形式。Meshyはこれらの形式のみを生成して返すため、タスクの時間を短縮できます。指定しない場合、Meshyは
3mfを除くすべての形式を生成します。3mfはリクエストされた場合にのみ生成されます。利用可能な値:
glbobjfbxstlusdz3mf
- Name
- alpha_thumbnail
- Type
- boolean
- デフォルト false
- Description
透明背景(RGBA)のプレビューも生成するかどうか。タスク取得時に
alpha_thumbnail_urlとして返されます。thumbnail_urlは変わりません。
- Name
- auto_size
- Type
- boolean
- デフォルト false
- Description
AIビジョンでオブジェクトの実世界での高さを推定し、それに合わせてモデルをリサイズするかどうか。
origin_atを設定しない限り、Meshyは原点を底面に置きます。
auto_size = true- Name
- origin_at
- Type
- string
- デフォルト bottom
- Description
モデルの原点を置く位置。
bottomまたはcenter。
返り値
レスポンスの result フィールドには、新しいText to 3Dタスクのidが保持されます。
失敗モード
- Name
400 - Bad Request- Description
リクエストを実行できません。エラーメッセージには検出された問題が示されます。例:
- パラメータの欠落:
promptやmodeなどの必須パラメータが欠落しています。 - プロンプトが長すぎる:
promptが文字数制限を超えています。 - Ultraでサポートされていないモデル:
geometry_resolutionが2kまたは4kだが、ai_modelがそれを実行できません。
リクエストを修正してから、再度送信してください。エラーを参照してください。
- パラメータの欠落:
- Name
401 - Unauthorized- Description
APIキーが欠落しているか無効です。
Authorizationヘッダーを確認してください。
- Name
402 - Payment Required- Description
例:
- クレジット不足: アカウントにこのタスクを実行するための十分なクレジットがない、またはアカウントがクレジット上限に達しています。クレジット残高を確認してから、再試行してください。
- 無料プラン: タスクを作成するには有料プランが必要です。サブスクリプション設定でプランをアップグレードしてから、再試行してください。
- Name
403 - Forbidden- Description
コンテンツモデレーションにより、promptまたは入力画像がブロックされました。入力を変更してから、再試行してください。
- Name
429 - Too Many Requests- Description
レート制限を超えました。しばらく待ってから再試行してください。レート制限を参照してください。
Text to 3DのrefineタスクをCreate
Text to 3Dのrefineタスクを作成し、完了したpreviewタスクのメッシュにテクスチャを付けます。成功したpreviewタスクのIDをpreview_task_idとして送信してください。Text to 3D previewタスクを作成を参照してください。これは2段階ワークフローの2番目のステップです。
タスクはバックグラウンドで実行されます。タスクにかかる一般的な時間については、処理時間を参照してください。
Request
# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "refine",
"preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"enable_pbr": true
}'
# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "refine",
"preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"target_formats": ["glb"],
"auto_size": true
}'
# Refine with Meshy N1 from the preview's stored reference image
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "refine",
"preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"ai_model": "meshy-n1"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
パラメータ
- Name
- mode
- Type
- string
- 必須
- Description
2段階ワークフローのステップです。refineタスクを作成するには
refineを送信してください。
- Name
- preview_task_id
- Type
- string
- 必須
- Description
テクスチャを付けるpreviewタスクのIDです。previewタスクのステータスは
SUCCEEDEDである必要があります。
- Name
- enable_pbr
- Type
- boolean
- デフォルト false
- Description
ベースカラーに加えてPBRマップ(メタリック、ラフネス、ノーマル)も生成するかどうかです。
ai_modelがmeshy-6の場合、Meshyはエミッションマップも生成しますが、texture_resolution: 8kの場合は除きます。meshy-6-lite、meshy-7、latestはエミッションマップを生成しません。ai_modelを設定していないmeshy-t2またはmeshy-t2.5のpreviewをrefineする場合も同様です。ai_model: meshy-n1の場合、trueを送信すると400が返されます。
- Name
- texture_resolution
- Type
- string
- デフォルト 2k
- Description
ベースカラーテクスチャの解像度です。refineタスクにのみ適用されます。previewでこのパラメータを送信すると
400が返されます。利用可能な値:
2k: 2048×20484k: 4096×40968k: 8192×8192
解像度が高いほど、より多くの表面の詳細が捉えられます。
4kと8kはai_modelがmeshy-6、meshy-7、またはlatestである必要があります。meshy-n1では400が返されます。8kでは、Meshyはエミッションマップを生成しません。
- Name
- hd_texture
- Type
- boolean
- ⚠ 非推奨
- デフォルト false
- Description
代わりに
texture_resolutionを送信してください。hd_texture: trueはtexture_resolution: "4k"と同じです。両方を送信した場合、Meshyはtexture_resolutionを使用します。
- Name
- texture_prompt
- Type
- string
- Description
テクスチャ付けの指針となるテキストで、最大800文字です。これを超える長さのテキストは
400を返します。texture_promptまたはtexture_image_urlのいずれかを送信し、両方は送信しないでください。両方を送信した場合、Meshyはtexture_promptを使用します。ai_model: meshy-n1の場合、これを送信すると400が返されます。
- Name
- texture_image_url
- Type
- string
- Description
テクスチャ付けの指針となる2D画像で、公開URLまたはbase64エンコードされたdata URI(
data:image/jpeg;base64,<your base64-encoded image data>など)として指定します。画像は
.jpg、.jpeg、.png、または.webpファイルで、最大20MB、各辺が最低32ピクセル、最大178,956,970ピクセル(幅×高さ)である必要があります。ai_model: meshy-n1の場合、Meshyはこの画像を正面図としてテクスチャ付けを行います。画像内の形状がモデルと大きく異なる場合、画像からのテクスチャ付けがうまく機能しないことがあります。
- Name
- ai_model
- Type
- string
- デフォルト inherited from the preview task
- Description
メッシュにテクスチャを付けるAIモデルです。メッシュはpreviewから引き継がれるため、refineでは
ai_modelはテクスチャモデルのみを選択します。利用可能な値:
meshy-7: Meshy 7latest: 最新のテクスチャモデル、現在はMeshy 7meshy-6: Meshy 6meshy-6-lite: Meshy 6 Litemeshy-n1: 参照画像のみから生成される2Kベースカラーテクスチャです。テキストprompt、PBRマップ、4Kまたは8Kはありません。
上記の値はテクスチャモデルです。省略すると、previewに一致するモデルでテクスチャが付けられます。値を送信すると上書きできます。
meshy-n1の場合、Meshyはtexture_image_urlからテクスチャを付けます。これを指定しない場合、Meshyはmeshy-7.1またはlatestのpreviewが保存している参照画像を使用します。それ以外のpreviewでは、texture_image_urlを送信しない限り400が返されます。previewの三角形数は最大7,999,999までです。四角形にremeshされたpreviewでは400が返されます。
- Name
- moderation
- Type
- boolean
- デフォルト false
- Description
生成前に
texture_promptとtexture_image_urlを有害なコンテンツがないか審査するかどうかです。Meshyが有害なコンテンツを検出した場合、リクエストは400を返し、Meshyはタスクを作成しません。
- Name
- remove_lighting
- Type
- boolean
- デフォルト true
- Description
ベースカラーテクスチャからハイライトと影を除去するかどうかです。よりクリーンな結果は、カスタム照明の下でより適切に機能します。
ai_modelがmeshy-6の場合にのみ効果があります。meshy-7とlatestはこれを受け付けますが無視し、ai_modelを設定していないmeshy-t2またはmeshy-t2.5のpreviewをrefineする場合も同様です。meshy-6-liteと一緒に送信すると400が返されます。meshy-n1の場合、trueを送信すると400が返されます。
- Name
- target_formats
- Type
- string[]
- Description
生成するファイル形式です。Meshyはこれらの形式のみを生成して返すため、タスクを短縮できる場合があります。省略した場合、Meshyは
3mfを除くすべての形式を生成します。3mfはリクエストした場合にのみ生成されます。利用可能な値:
glbobjfbxstlusdz3mf
- Name
- alpha_thumbnail
- Type
- boolean
- デフォルト false
- Description
透明背景(RGBA)のプレビューも併せてレンダリングするかどうかです。タスクを取得した際に
alpha_thumbnail_urlとして返されます。thumbnail_urlは変更されません。
- Name
- auto_size
- Type
- boolean
- デフォルト false
- Description
AIビジョンでオブジェクトの実世界での高さを推定し、モデルをそのサイズにリサイズするかどうかです。
origin_atを設定しない限り、Meshyは原点を底部に置きます。
auto_size = true- Name
- origin_at
- Type
- string
- デフォルト bottom
- Description
モデルの原点をどこに置くか、
bottomまたはcenterです。
返り値
レスポンスのresultフィールドには、新しいText to 3Dタスクのidが格納されます。
失敗モード
- Name
400 - Bad Request- Description
リクエストを実行できません。エラーメッセージには、どの問題が検出されたかが記載されています。例:
- Invalid task ID:
preview_task_idが無効であるか、あなたのpreviewタスクのいずれとも一致しません。 - Task not ready: previewタスクがまだ成功していません。
- Model mismatch: previewタスクのAIモデルが、要求されたrefineモデルと互換性がありません。
- Unsupported model for remove_lighting:
remove_lightingがai_model: "meshy-6-lite"とともに送信されました。 - No reference image for Meshy N1:
ai_model: meshy-n1がtexture_image_urlなしで送信され、previewにはMeshy N1が使用できる参照画像がありません。texture_image_urlを送信してください。 - Quad preview for Meshy N1:
ai_model: meshy-n1が四角形にremeshされたpreviewに対して送信されました。別のai_modelでrefineしてください。 - Too many triangles for Meshy N1:
ai_model: meshy-n1の場合、previewの三角形数が7,999,999を超えています。別のai_modelでrefineしてください。 - Unsupported option for Meshy N1:
ai_model: meshy-n1が次のいずれかのオプションとともに送信されました:texture_promptenable_pbr: true4kまたは8kのtexture_resolutiontexture_resolutionなしのhd_texture: trueremove_lighting: true
リクエストを修正してから、再送信してください。エラーを参照してください。
- Invalid task ID:
- Name
401 - Unauthorized- Description
APIキーが見つからないか無効です。
Authorizationヘッダーを確認してください。
- Name
402 - Payment Required- Description
例:
- Insufficient credits: アカウントにこのタスクを実行するための十分なクレジットがないか、アカウントがクレジット上限に達しました。クレジット残高を確認してから、再試行してください。
- Free plan: タスクの作成には有料プランが必要です。サブスクリプション設定でプランをアップグレードしてから、再試行してください。
- Name
403 - Forbidden- Description
コンテンツmoderationがpromptまたは入力画像をブロックしました。入力を変更してから、再試行してください。
- Name
429 - Too Many Requests- Description
レート制限を超えました。しばらく待ってから、再試行してください。レート制限を参照してください。
テキストから3Dタスクを取得
IDを指定してテキストから3Dタスクを返します。これはpreviewタスクとrefineタスクの両方で機能します。
Request
curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"prompt": "a monster mask",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
パラメータ
- Name
- id
- Type
- path
- Description
作成時のレスポンスから取得したタスクIDです。
戻り値
例
次の表は、各modeにおけるサンプルモデルを示しています。
| Mode | サンプルモデル |
|---|---|
| Preview | ![]() |
| Refine | ![]() |
Text to 3Dタスクを削除
Text to 3Dタスクを、そのモデルやデータを含めて完全に削除します。削除は元に戻せません。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v2/text-to-3d/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."
}
パスパラメータ
- Name
- id
- Type
- path
- Description
削除するタスクのID。
タスクのステータス
PENDING のタスクを削除すると、作成時に使用したクレジットが返金されます。
IN_PROGRESS のタスクは削除できません。リクエストは 409 Conflict を返し、
タスクは実行を続けます。Meshyは開始済みのタスクについては返金を行わないため、
削除するとクレジットと結果の両方を失うことになります。
SUCCEEDED、FAILED、または CANCELED のいずれかの状態になるまで待ってから削除してください。
最終ステータス(SUCCEEDED、FAILED、または CANCELED)にあるタスクを削除しても、
クレジットは返金されません。
戻り値
タスクが削除された場合は 200 OK、タスクが IN_PROGRESS の場合は 409 Conflict を返します。
Text to 3Dタスク一覧の取得
あなたのText to 3Dタスクの一覧を返します。
Request
curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"prompt": "a monster mask",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
]
パラメータ
- Name
- page_num
- Type
- integer
- デフォルト 1
- Description
返すページ番号。最大
255まで指定できます。これより大きい値を指定すると400が返されます。
- Name
- page_size
- Type
- integer
- デフォルト 10
- Description
1ページあたりのタスク数。最大
100まで指定できます。
- Name
- sort_by
- Type
- string
- Description
ソート順。
利用可能な値:
+created_at:古い順-created_at:新しい順
戻り値
Text to 3Dタスクオブジェクトのページネーションされた一覧。
Text to 3Dタスクをストリームする
Text to 3Dタスクの更新をServer-Sent Events(SSE)としてストリーム配信します。
Request
curl -N https://api.meshy.ai/openapi/v2/text-to-3d/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",
"progress": 50,
"status": "IN_PROGRESS"
}
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
パラメーター
- Name
- id
- Type
- path
- Description
作成時のレスポンスに含まれるタスクID。
レスポンス
Text to 3DタスクオブジェクトのストリームをServer-Sent Eventsとして返します。
各イベントには、Getエンドポイントが返すものと同じ形式で、タスクオブジェクト全体が含まれます。タスクがPENDINGまたはIN_PROGRESSの間は、結果フィールドにまだ値がありません。
Text to 3Dタスクオブジェクト
Text to 3Dタスクオブジェクトは、テキストプロンプトから3Dモデルを生成する1つのタスクを表します。ステータス、progress、そしてタスクが成功した場合はモデルファイルを保持します。テキストから3Dにはpreviewとrefineの2つの段階があります。previewタスクはメッシュのみの3Dモデルを生成し、refineタスクはpreviewの結果からテクスチャ付きの3Dモデルを生成します。
プロパティ
Example Text to 3D Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
},
"prompt": "a monster mask",
"texture_prompt": "green slimy skin with scales and warts",
"texture_image_url": "",
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
- Name
- id
- Type
- string
- Description
タスクID。不透明な文字列として扱い、その形式に依存しないでください。
- Name
- type
- Type
- string
- Description
タスクの種類。previewタスクの場合は
text-to-3d-preview、refineタスクの場合はtext-to-3d-refineです。
- Name
- model_urls
- Type
- object
- Description
生成された3DモデルのダウンロードURL。ファイル形式ごとに1つずつあります。タスクが生成しなかった形式には、空文字列ではなくキー自体がありません。
- Name
glb- Type
- string
- Description
GLBファイル。
- Name
fbx- Type
- string
- Description
FBXファイル。
- Name
usdz- Type
- string
- Description
USDZファイル。
- Name
obj- Type
- string
- Description
OBJファイル。
- Name
mtl- Type
- string
- Description
MTLファイル。
- Name
stl- Type
- string
- Description
STLファイル。
- Name
3mf- Type
- string
- Description
3MFファイル。
target_formatsに3mfが含まれる場合にのみ存在します。
- Name
- prompt
- Type
- string
- Description
タスクを作成する際に送信した
prompt(変更なし)。
- Name
- texture_prompt
- Type
- string
- Description
refine段階でのテクスチャリングを誘導するために送信したテキストプロンプト。
- Name
- ultra_mode
- Type
- boolean
- ⚠ 非推奨
- Description
代わりに
geometry_resolutionを参照してください。
- Name
- geometry_resolution
- Type
- string
- Description
previewタスクが実行されたUltra階層。
2kまたは4k。standardの場合、このフィールドはありません。
- Name
- texture_image_url
- Type
- string
- Description
テクスチャリングを誘導するために送信した画像のダウンロードURL。
- Name
- thumbnail_url
- Type
- string
- Description
3Dモデルのサムネイル画像のダウンロードURL。
- Name
- alpha_thumbnail_url
- Type
- string
- Description
背景が透明(RGBA)になっている
thumbnail_urlのバージョンのダウンロードURL。alpha_thumbnail: trueを指定してタスクを作成し、Meshyが透明プレビューをレンダリングした場合にのみ存在します。
- Name
- progress
- Type
- integer
- Description
タスクの進行度合い(パーセンテージ)。タスクが開始するまでは
0で、成功すると100になります。
- Name
- started_at
- Type
- timestamp
- Description
タスクが開始した時刻(Unixミリ秒)。タスクが開始するまでは
0です。
- Name
- created_at
- Type
- timestamp
- Description
タスクが作成された時刻(Unixミリ秒)。
- Name
- finished_at
- Type
- timestamp
- Description
タスクが終了した時刻(Unixミリ秒)。タスクが終了するまでは
0です。
- Name
- status
- Type
- string
- Description
タスクのステータス。
PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELEDのいずれかです。
- Name
- texture_urls
- Type
- array
- Description
生成されたテクスチャマップのダウンロードURL。オブジェクトの配列として提供されます。通常は1つのオブジェクトを保持します。各オブジェクトには以下のフィールドがあります。
- Name
base_color- Type
- string
- Description
ベースカラーマップ。
- Name
metallic- Type
- string
- Description
メタリックマップ。
enable_pbr: falseを指定してタスクを作成した場合は存在しません。
- Name
normal- Type
- string
- Description
ノーマルマップ。
enable_pbr: falseを指定してタスクを作成した場合は存在しません。
- Name
roughness- Type
- string
- Description
ラフネスマップ。
enable_pbr: falseを指定してタスクを作成した場合は存在しません。
- Name
emission- Type
- string
- Description
エミッションマップ。以下のいずれかの場合は存在しません。
enable_pbr: falseを指定してタスクを作成した場合。ai_modelがmeshy-6-lite、meshy-7、meshy-7.1、またはlatestの場合。texture_resolutionが8kの場合。ai_modelを設定せずにmeshy-t2またはmeshy-t2.5のpreviewをrefineするタスクの場合。
- Name
- preceding_tasks
- Type
- integer
- Description
キュー内でこのタスクより前にあるタスクの数。この値はタスクが
PENDINGの間のみ意味を持ちます。
- Name
- task_error
- Type
- object
- Description
タスクが失敗した場合のエラー詳細。ステータスが
FAILEDでない限りnullです。エラーを参照してください。
- Name
- consumed_credits
- Type
- integer
- Description
タスクが使用したクレジットの数。ステータスが
PENDING、IN_PROGRESS、SUCCEEDEDのいずれかの場合に存在します。FAILEDタスクの場合は0です。これは、タスクが失敗した場合にMeshyがクレジットを返金するためです。

