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

テキストから3D API

自分のアプリケーションでテキストプロンプトから3Dモデルを生成します。

テキストから3Dは2つのステップで動作します。まず、preview タスク(mode: "preview")を作成して、テクスチャのない3Dメッシュを生成し、形状を確認できるようにします。次に、成功したプレビューのタスクIDを refine タスク(mode: "refine")に送信して、メッシュにテクスチャを付けます。どちらのステップも同じエンドポイントを使用します。


POST/openapi/v2/text-to-3d

Text to 3DのプレビュータスクをCreate

テキストprompt からテクスチャなしの3Dメッシュ(ジオメトリのみ)を生成する、Text to 3Dのプレビュータスクを作成します。これは2段階ワークフローの最初のステップです。プレビューが成功したら、そのタスクIDをrefineタスクに送信してメッシュにテクスチャを適用します。Text to 3Dのrefineタスクを作成を参照してください。完全なレスポンススキーマについては、Text to 3Dタスクオブジェクトを参照してください。

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

Request

POST
/openapi/v2/text-to-3d
# 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-lite
    • meshy-6
    • meshy-7.1
    • latest: Meshy 7.1
    • meshy-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 を返します。

    利用可能な値:

    • standard
    • 2k: 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: ultra
    • 2: high
    • 3: medium
    • 4: 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 ~ 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
    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 はリクエストされた場合にのみ生成されます。

    利用可能な値:

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

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


POST/openapi/v2/text-to-3d

Text to 3DのrefineタスクをCreate

Text to 3Dのrefineタスクを作成し、完了したpreviewタスクのメッシュにテクスチャを付けます。成功したpreviewタスクのIDをpreview_task_idとして送信してください。Text to 3D previewタスクを作成を参照してください。これは2段階ワークフローの2番目のステップです。

タスクはバックグラウンドで実行されます。タスクにかかる一般的な時間については、処理時間を参照してください。

Request

POST
/openapi/v2/text-to-3d
# 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×2048
    • 4k: 4096×4096
    • 8k: 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 7
    • latest: 最新のテクスチャモデル、現在はMeshy 7
    • meshy-6: Meshy 6
    • meshy-6-lite: Meshy 6 Lite
    • meshy-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はリクエストした場合にのみ生成されます。

    利用可能な値:

    • glb
    • obj
    • fbx
    • stl
    • usdz
    • 3mf
  • 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_prompt
      • enable_pbr: true
      • 4kまたは8kのtexture_resolution
      • texture_resolutionなしのhd_texture: true
      • remove_lighting: true

    リクエストを修正してから、再送信してください。エラーを参照してください。

  • 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

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


GET/openapi/v2/text-to-3d/:id

テキストから3Dタスクを取得

IDを指定してテキストから3Dタスクを返します。これはpreviewタスクとrefineタスクの両方で機能します。

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
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です。

戻り値

テキストから3Dタスクオブジェクト。

例

次の表は、各modeにおけるサンプルモデルを示しています。

Modeサンプルモデル
PreviewPreview model
RefineRefined model

DELETE/openapi/v2/text-to-3d/:id

Text to 3Dタスクを削除

Text to 3Dタスクを、そのモデルやデータを含めて完全に削除します。削除は元に戻せません。

Request

DELETE
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
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 を返します。


GET/openapi/v2/text-to-3d

Text to 3Dタスク一覧の取得

あなたのText to 3Dタスクの一覧を返します。

Request

GET
/openapi/v2/text-to-3d
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タスクオブジェクトのページネーションされた一覧。


GET/openapi/v2/text-to-3d/:id/stream

Text to 3Dタスクをストリームする

Text to 3Dタスクの更新をServer-Sent Events(SSE)としてストリーム配信します。

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
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がクレジットを返金するためです。