画像から3D API
画像を、テクスチャ付きまたはテクスチャなしの3Dモデルへ、お好みの形式で変換します。画像を送信するか、テキストから画像または画像から画像タスクの出力を使用してください。
Image to 3Dタスクを作成する
Image to 3Dタスクを作成します。タスクはバックグラウンドで実行されます。タスクに通常どれくらいかかるかについては、処理時間を参照してください。
Request
# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible image url or base64-encoded data URI>"
}'
# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible image url or base64-encoded data URI>",
"ai_model": "meshy-7.1",
"geometry_resolution": "4k",
"enable_pbr": true,
"should_remesh": true,
"target_polycount": 100000,
"should_texture": true,
"pose_mode": "a-pose",
"target_formats": ["glb"]
}'
# Textured with Meshy N1 from the input image
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible image url or base64-encoded data URI>",
"ai_model": "meshy-7.1",
"texture_model": "meshy-n1"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
パラメータ
- Name
- input_task_id
- Type
- string
- 必須
- Description
image_urlを送信しない場合は必須です。入力として使用したい画像を持つ、Text to ImageまたはImage to Imageタスクの ID です。そのタスクは API で作成したもので、ステータスがSUCCEEDEDであり、ちょうど1枚の画像を生成したものである必要があります。
- Name
- image_url
- Type
- string
- 必須
- Description
input_task_idを送信しない場合は必須です。3Dモデルに変換する画像を、公開URLまたはbase64エンコードされたdata URI(例:data:image/jpeg;base64,<your base64-encoded image data>)として指定します。両方送信した場合、Meshyはinput_task_idを使用します。画像は、最大20MBのJPG、JPEG、PNG、またはWebPファイルで、各辺が32ピクセル以上、最大178,956,970ピクセル(幅×高さ)である必要があります。
- Name
- model_type
- Type
- string
- デフォルト standard
- Description
生成する3Dメッシュの種類です。
指定可能な値:
standard: 高詳細なメッシュsmart-topology: Smart Topologyモデルによるメッシュで、ai_model(meshy-t2またはmeshy-t2.5)で選択します
smart-topologyの場合、Meshyはshould_remesh、save_pre_remeshed_model、decimation_modeを無視し、topology: triangleのみを受け付けます。
- Name
- ai_model
- Type
- string
- デフォルト latest
- Description
3Dモデルを生成するAIモデルです。指定可能な値は
model_typeによって異なります。標準モデル(
model_type: standard):latest: Meshy 7.1meshy-7.1meshy-6meshy-6-litemeshy-7(非推奨): 代わりにmeshy-7.1を使用してください。2026年12月31日に廃止されます。
Smart Topologyモデル(
model_type: smart-topology)は三角形を生成し、面数はtarget_polycountで設定できます:meshy-t2: よりクリーンなtopologyとネイティブに分離されたパーツmeshy-t2.5(デフォルト): ゲームアセット向けの鮮明なディテール
ゲームキャラクターや3Dプリントなど、あなたのプロジェクトに適したモデルについては、モデルを参照してください。
- Name
- geometry_resolution
- Type
- string
- デフォルト standard
- Description
ジオメトリ生成パスです。
指定可能な値:
standard2k: 2048³でUltraパスを実行4k: 4096³でUltraパスを実行し、最も詳細な表面を得る
2kにはmeshy-7.1、latest、または非推奨のmeshy-7が必要です。4kにはmeshy-7.1またはlatestが必要です。
- Name
- ultra_mode
- Type
- boolean
- ⚠ 非推奨
- デフォルト false
- Description
代わりに
geometry_resolutionを使用してください。ultra_mode: trueはgeometry_resolution: "2k"と同じです。
- Name
- should_texture
- Type
- boolean
- デフォルト true
- Description
テクスチャを生成するかどうかです。
trueの場合はテクスチャ付きモデルを返し、falseの場合はテクスチャリングをスキップしてテクスチャなしのメッシュを返します。
should_texture = true- Name
- texture_model
- Type
- string
- デフォルト depends on ai_model
- Description
同じタスク内で3Dモデルにテクスチャを付けるAIモデルです。省略すると、
ai_modelに対応するデフォルトのテクスチャモデルが使用されます。クレジットコストは変わりません。指定可能な値:
meshy-7: Meshy 7、PBRマップと最大8Kのテクスチャに対応meshy-n1: Meshy N1、参照画像のみから生成される2Kのベースカラーテクスチャmeshy-6-lite: Meshy 6 Lite、最も低コストの2Kテクスチャmeshy-6: Meshy 6、ai_model: meshy-6のデフォルトとしてのみ使用可能
すべての
ai_modelでmeshy-7、meshy-n1、meshy-6-liteを指定できます。選択したテクスチャモデルがサポートしないオプションを指定すると400が返されます。meshy-n1の場合、生成されたモデルが7,999,999三角形を超えるとタスクは失敗し、Meshyはそのクレジットを払い戻します。should_texture: falseの場合、Meshyはtexture_modelを無視しますが、未知の値を指定すると400が返されます。各テクスチャモデルの機能と選び方については、モデルを参照してください。
- Name
- enable_pbr
- Type
- boolean
- デフォルト false
- Description
ベースカラーに加えてPBRマップ(メタリック、ラフネス、ノーマル)も生成するかどうかです。
trueにはshould_texture: trueが必要で、should_texture: falseの場合は400を返します。texture_model: meshy-n1の場合、trueは400を返します。Meshy 6テクスチャモデルは、
texture_resolution: 8kの場合を除き、エミッションマップも生成します。
- Name
- texture_resolution
- Type
- string
- デフォルト 2k
- Description
ベースカラーテクスチャのサイズです。テクスチャが大きいほど、より多くの表面ディテールを捉えられます。
指定可能な値:
2k: 2048×20484k: 4096×40968k: 8192×8192
4kと8kにはMeshy 7またはMeshy 6テクスチャモデルが必要で、それ以外では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_model: meshy-n1の場合、これを送信すると400を返します。
- Name
- texture_image_url
- Type
- string
- Description
テクスチャを導く画像で、公開URLまたはbase64エンコードされたdata URI(例:
data:image/jpeg;base64,<your base64-encoded image data>)として指定します。画像は、最大20MBのJPG、JPEG、PNG、またはWebPファイルで、各辺が32ピクセル以上、最大178,956,970ピクセル(幅×高さ)である必要があります。Meshyは
texture_promptとtexture_image_urlのいずれか一方のみでテクスチャを導きます。両方送信した場合、Meshyはtexture_promptを使用します。テクスチャリングのクレジットコストについては、料金を参照してください。texture_model: meshy-n1の場合、Meshyはこの画像を正面視点としてテクスチャを生成します。省略した場合は入力画像を使用します。画像の形状が3Dモデルのジオメトリと大きく異なる場合、画像からのテクスチャリングはうまく機能しないことがあります。
- 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の出力は三角形のみであるため、
meshy-t2またはmeshy-t2.5でquadを指定すると400を返します。texture_model: meshy-n1の場合、モデルがリメッシュされる際にquadは400を返します。これはmeshy-6-liteではデフォルトで発生します。
- Name
- decimation_mode
- Type
- integer
- Description
レベル別のアダプティブ面数です。これを設定すると、Meshyは
target_polycountを無視します。指定可能な値:
1: ultra2: high3: medium4: low
- Name
- save_pre_remeshed_model
- Type
- boolean
- デフォルト false
- Description
リメッシュフェーズの前のモデルのGLBも保存するかどうかです。Meshyはそれを
model_urls.pre_remeshed_glbで返します。
- 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
- surface_mode
- Type
- string
- ⚠ 非推奨
- Description
代わりに
ai_modelを使用してください。これが選択していたモデル生成方式は廃止されているため、出力に影響しません。指定可能な値は
organicとhardです。それ以外の値は400を返します。
- Name
- image_enhancement
- Type
- boolean
- デフォルト true
- Description
生成前に入力画像を最適化するかどうかです。
falseの場合、スタイル処理を行わず、入力画像の見た目をそのまま維持します。これは
meshy-6、meshy-7.1、latestでのみ機能します。meshy-6-liteまたはmodel_type: smart-topologyの場合、400を返します。
- Name
- remove_lighting
- Type
- boolean
- デフォルト true
- Description
ベースカラーテクスチャからハイライトと影を除去するかどうかです。結果はよりクリーンになり、独自のライティング下でより良く機能します。
これはMeshy 6テクスチャモデルでのみ有効で、サポートしていないテクスチャモデルで
trueを指定すると400を返します。model_type: smart-topologyの場合、またはai_model: meshy-6-liteとそのデフォルトのテクスチャモデルの場合、これを送信すると400を返します。
- Name
- moderation
- Type
- boolean
- デフォルト false
- Description
生成前に、以下の入力に有害なコンテンツがないか審査するかどうかです:
image_urltexture_image_urltexture_prompt
Meshyが有害なコンテンツを検出した場合、リクエストは
400を返し、Meshyはタスクを作成しません。
- Name
- target_formats
- Type
- string[]
- Description
生成するファイル形式です。Meshyはリストに挙げた形式のみを生成して返し、これによりタスクを短縮できます。省略した場合、Meshyは
3mfを除くすべての形式を生成します。3mfはリストに指定した場合にのみ取得できます。指定可能な値:
glbobjfbxstlusdz3mf
- Name
- auto_size
- Type
- boolean
- デフォルト false
- Description
AIビジョンでオブジェクトの実世界での高さを推定し、モデルをそのサイズにリサイズするかどうかです。
origin_atを設定しない限り、Meshyは原点を底部に配置します。
- Name
- alpha_thumbnail
- Type
- boolean
- デフォルト false
- Description
透明な背景(RGBA)のプレビューも生成するかどうかです。タスクを取得する際に
alpha_thumbnail_urlで返されます。thumbnail_urlは変わりません。
- Name
- multi_view_thumbnails
- Type
- boolean
- デフォルト false
- Description
前面、右側面、背面、左側面のプレビューも生成するかどうかです。タスクを取得する際に
thumbnail_urlsで返されます。thumbnail_urlは変わらず、引き続き正面視点を示します。これによりタスクに約5秒が追加されます。
auto_size = true- Name
- origin_at
- Type
- string
- デフォルト bottom
- Description
モデルの原点をどこに置くか、
bottomまたはcenterです。
戻り値
レスポンスのresultフィールドには、新しく作成されたImage to 3Dタスクの ID が格納されます。
失敗モード
- Name
400 - Bad Request- Description
リクエストを実行できません。エラーメッセージには検出された問題が示されます。例:
- パラメータの欠落:
image_urlもinput_task_idも送信されていません。 - 無効な入力タスク:
input_task_idが、ちょうど1枚の画像を生成したSUCCEEDEDのText to ImageまたはImage to Imageタスクではありません。 - 無効な画像形式:
image_urlの画像がJPG、JPEG、PNG、またはWebPファイルではありません。 - 到達不能なURL: URLが
404を返すかタイムアウトするため、Meshyがimage_urlの画像をダウンロードできません。 - 画像サイズが大きすぎる:
image_urlまたはtexture_image_urlの画像が20MBを超えています。 - 無効な画像サイズ:
image_urlまたはtexture_image_urlの画像の辺が32ピクセル未満、または178,956,970ピクセル(幅×高さ)を超えています。 - 無効なdata URI: base64文字列の形式が不正です。
- 無効なパラメータの組み合わせ:
enable_pbrがtrueで、should_textureがfalseです。 - Ultraでサポートされないモデル:
geometry_resolutionが2kまたは4kで、それを実行できないai_modelが指定されています。 - 画像オプションでサポートされないモデル: 以下のいずれか:
ai_model: "meshy-6-lite"またはmodel_type: "smart-topology"でimage_enhancementが送信されました。model_type: "smart-topology"で、またはai_model: "meshy-6-lite"とそのデフォルトのテクスチャモデルでremove_lightingが送信されました。
- 無効なテクスチャモデル:
texture_modelが指定可能な値のいずれでもありません。 - 利用できないテクスチャモデル:
texture_modelがmeshy-6で、ai_modelがmeshy-6以外です。meshy-7、meshy-n1、meshy-6-liteを送信するか、省略してください。 - テクスチャモデルでサポートされないオプション: リクエストが、テクスチャモデルがサポートしていないオプション(
meshy-n1でのenable_pbr: trueやmeshy-6-liteでの4kテクスチャなど)を要求しています。モデルを参照してください。
リクエストを修正してから、再度送信してください。エラーを参照してください。
- パラメータの欠落:
- Name
401 - Unauthorized- Description
APIキーが欠落しているか無効です。
Authorizationヘッダーを確認してください。
- Name
402 - Payment Required- Description
例:
- クレジット不足: アカウントにこのタスクに必要なクレジットが不足しているか、アカウントがクレジット上限に達しています。クレジット残高を確認してから再試行してください。
- 無料プラン: タスクの作成には有料プランが必要です。サブスクリプション設定でプランをアップグレードしてから再試行してください。
- Name
403 - Forbidden- Description
コンテンツ審査がプロンプトまたは入力画像をブロックしました。入力を変更してから再試行してください。
- Name
404 - Not Found- Description
input_task_idがあなたのタスクのいずれとも一致しません。タスクIDを確認してから、再度リクエストを送信してください。
- Name
429 - Too Many Requests- Description
レート制限を超えました。しばらく待ってから再試行してください。レート制限を参照してください。
Image to 3D タスクを取得する
IDを指定してImage to 3Dタスクを返します。
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-3d",
"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=***",
"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=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"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": 30
}
画像から3Dタスクを削除
画像から3Dタスクを、モデルやデータを含めて完全に削除します。削除は元に戻せません。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/image-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 が返されます。
画像から3Dタスク一覧の取得
あなたの画像から3Dタスクの一覧を返します。
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-3d",
"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=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"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": 30
}
]
パラメータ
- Name
- page_num
- Type
- integer
- デフォルト 1
- Description
返すページ番号。最大
255。これより大きい値を指定すると400が返されます。
- Name
- page_size
- Type
- integer
- デフォルト 10
- Description
ページごとのタスク数。最大
100。
- Name
- sort_by
- Type
- string
- Description
並び順。
使用可能な値:
+created_at: 作成日時の古い順-created_at: 作成日時の新しい順
戻り値
ページ分割された 画像から3Dタスクオブジェクト のリスト。
Image to 3D タスクをストリーミングする
Image to 3D タスクの更新を Server-Sent Events (SSE) としてストリーミングします。
Request
curl -N https://api.meshy.ai/openapi/v1/image-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",
"type": "image-to-3d",
"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=***",
"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=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"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": 30
}
パラメータ
- Name
- id
- Type
- path
- Description
作成レスポンスから取得したタスク ID。
返り値
Image to 3D タスクオブジェクトのストリームを Server-Sent Events として返します。
各イベントには、Get エンドポイントが返すものと同じ形式で、タスクオブジェクト全体が含まれます。タスクが PENDING または IN_PROGRESS の間は、結果フィールドにはまだ値が入っていません。
画像から3Dタスクオブジェクト
画像から3Dタスクオブジェクトは、画像から3Dモデルを生成する1回のタスクを表します。ステータス、progress、そしてタスクが成功した際のモデルファイルを保持します。
プロパティ
Example Image to 3D Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "image-to-3d",
"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=***",
"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=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"texture_image_url": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"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": 30
}
- Name
- id
- Type
- string
- Description
タスクID。不透明な文字列として扱い、その形式に依存しないでください。
- Name
- type
- Type
- string
- Description
タスクタイプで、常に
image-to-3dです。
- Name
- model_urls
- Type
- object
- Description
生成された3DモデルのダウンロードURLで、ファイル形式ごとに1つずつ存在します。タスクが生成しなかった形式には、空文字列ではなくキー自体がありません。
- Name
glb- Type
- string
- Description
GLBファイル。
- Name
fbx- Type
- string
- Description
FBXファイル。
- Name
obj- Type
- string
- Description
OBJファイル。
- Name
usdz- Type
- string
- Description
USDZファイル。
- Name
mtl- Type
- string
- Description
MTLファイル。モデルにテクスチャがある場合、OBJファイルと共に返されます。
- Name
stl- Type
- string
- Description
STLファイル。
- Name
3mf- Type
- string
- Description
3MFファイル。
target_formatsに3mfが含まれている場合のみ存在します。
- Name
pre_remeshed_glb- Type
- string
- Description
リメッシュ前のGLBファイル。
should_remesh: trueとsave_pre_remeshed_model: trueの両方を指定してタスクを作成した場合のみ存在します。
- Name
- thumbnail_url
- Type
- string
- Description
3Dモデルのプレビュー画像のダウンロードURL。
thumbnail_urlsが存在する場合、これはthumbnail_urls.frontと同じ画像です。後方互換性のためにMeshyが保持しています。
- Name
- alpha_thumbnail_url
- Type
- string
- Description
透明な背景(RGBA)を持つ
thumbnail_urlのバージョンのダウンロードURL。alpha_thumbnail: trueを指定してタスクを作成し、かつMeshyが透明プレビューをレンダリングした場合のみ存在します。
- Name
- thumbnail_urls
- Type
- object
- Description
4方向から見た3DモデルのプレビューのダウンロードURL。各値は、
thumbnail_urlと同じマテリアルとライティングでレンダリングされた、署名付きの512×512 PNGへのURLです。例えばバッチ処理のパイプラインなどで、GLBをダウンロードせずに複数の角度からモデルをプレビューするために使用できます。multi_view_thumbnails: trueを指定してタスクを作成し、タスクがSUCCEEDEDに到達した場合のみ存在します。multi_view_thumbnails: trueを指定せずに作成されたタスクには、このフィールドは含まれません。- Name
- front
- Type
- string
- Description
垂直軸を中心として0°の正面ビュー。
thumbnail_urlと一致します。
- Name
- right
- Type
- string
- Description
90°の右側ビュー。
- Name
- back
- Type
- string
- Description
180°の背面ビュー。
- Name
- left
- Type
- string
- Description
270°の左側ビュー。
- Name
- texture_prompt
- Type
- string
- Description
テクスチャを導いたテキストprompt。
- Name
- texture_image_url
- Type
- string
- Description
テクスチャを導いた画像のダウンロードURL。
- Name
- ultra_mode
- Type
- boolean
- ⚠ 非推奨
- Description
代わりに
geometry_resolutionを参照してください。
- Name
- geometry_resolution
- Type
- string
- Description
タスクが実行されたUltraティアで、
2kまたは4kです。standardのタスクには、このフィールドは含まれません。
- Name
- progress
- Type
- integer
- Description
タスクがどれだけ完了しているかをパーセンテージで表します。タスクが開始するまでは
0で、成功すると100になります。
- Name
- started_at
- Type
- timestamp
- Description
タスクが開始した時刻(Unixミリ秒)。タスクが開始するまでは
0です。
- Name
- created_at
- Type
- timestamp
- Description
タスクが作成された時刻(Unixミリ秒)。
- Name
- expires_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
タスクが生成したテクスチャマップで、オブジェクトの配列として表されます。通常は1つのオブジェクトを保持し、以下のフィールドを持ちます。
- Name
base_color- Type
- string
- Description
ベースカラーマップのダウンロードURL。
- Name
metallic- Type
- string
- Description
メタリックマップのダウンロードURL。
enable_pbr: falseを指定してタスクを作成した場合、このフィールドは存在しません。
- Name
normal- Type
- string
- Description
ノーマルマップのダウンロードURL。
enable_pbr: falseを指定してタスクを作成した場合、このフィールドは存在しません。
- Name
roughness- Type
- string
- Description
ラフネスマップのダウンロードURL。
enable_pbr: falseを指定してタスクを作成した場合、このフィールドは存在しません。
- Name
emission- Type
- string
- Description
エミッションマップのダウンロードURL。Meshyは、以下すべてを指定してタスクを作成した場合にのみこれを含めます。
ai_model: meshy-6、そのデフォルトのテクスチャモデルを使用enable_pbr: truetexture_resolutionが2kまたは4k
- 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はクレジットを返金するためです。