lowpoly は 2026/10/30 に廃止されます。 3D 生成モデルとしての meshy-7 は 2026/12/31 に廃止されます。テクスチャモデルとしては引き続き利用できます。 リクエストエラーを避けるため、これらの日付までにモデルを切り替えてください。 非推奨の一覧を見る

画像から3D API

画像を、テクスチャ付きまたはテクスチャなしの3Dモデルへ、お好みの形式で変換します。画像を送信するか、テキストから画像または画像から画像タスクの出力を使用してください。


POST/openapi/v1/image-to-3d

Image to 3Dタスクを作成する

Image to 3Dタスクを作成します。タスクはバックグラウンドで実行されます。タスクに通常どれくらいかかるかについては、処理時間を参照してください。

Request

POST
/openapi/v1/image-to-3d
# 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.1
    • meshy-7.1
    • meshy-6
    • meshy-6-lite
    • meshy-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

    ジオメトリ生成パスです。

    指定可能な値:

    • standard
    • 2k: 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×2048
    • 4k: 4096×4096
    • 8k: 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はこの画像を正面視点としてテクスチャを生成します。省略した場合は入力画像を使用します。

  • 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: ultra
    • 2: high
    • 3: medium
    • 4: 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から30000030000
    meshy-t2100から150004000
    meshy-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_url
    • texture_image_url
    • texture_prompt

    Meshyが有害なコンテンツを検出した場合、リクエストは400を返し、Meshyはタスクを作成しません。

  • Name
    target_formats
    Type
    string[]
    Description

    生成するファイル形式です。Meshyはリストに挙げた形式のみを生成して返し、これによりタスクを短縮できます。省略した場合、Meshyは3mfを除くすべての形式を生成します。3mfはリストに指定した場合にのみ取得できます。

    指定可能な値:

    • glb
    • obj
    • fbx
    • stl
    • usdz
    • 3mf
  • 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

    レート制限を超えました。しばらく待ってから再試行してください。レート制限を参照してください。


GET/openapi/v1/image-to-3d/:id

Image to 3D タスクを取得する

IDを指定してImage to 3Dタスクを返します。

Request

GET
/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
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
}

パラメータ

  • Name
    id
    Type
    path
    Description

    作成レスポンスから取得したタスクID。

戻り値

Image to 3D タスクオブジェクト。


DELETE/openapi/v1/image-to-3d/:id

画像から3Dタスクを削除

画像から3Dタスクを、モデルやデータを含めて完全に削除します。削除は元に戻せません。

Request

DELETE
/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
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 が返されます。


GET/openapi/v1/image-to-3d

画像から3Dタスク一覧の取得

あなたの画像から3Dタスクの一覧を返します。

Request

GET
/openapi/v1/image-to-3d
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タスクオブジェクト のリスト。


GET/openapi/v1/image-to-3d/:id/stream

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

Image to 3D タスクの更新を Server-Sent Events (SSE) としてストリーミングします。

Request

GET
/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
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: true
      • texture_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はクレジットを返金するためです。