テキストから3D API

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

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

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

Create a Text to 3D preview task

Text to 3Dのpreviewタスクを作成します。このタスクはテキストのpromptから、テクスチャのない3Dメッシュ（ジオメトリのみ）を生成します。これは2段階ワークフローの最初のステップです。previewが成功したら、そのタスク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タスクを作成するには 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 を送信してください
Smart Topologyモデル（model_type: smart-topology）:
- meshy-t2: よりクリーンなtopology、ネイティブに分離されたパーツ、三角形出力、target_polycount で設定する面数
- meshy-t2.5（デフォルト）: ゲームアセット向けのよりシャープなディテール、三角形出力、target_polycount で設定する面数
Name
geometry_resolution
Type
string
デフォルト standard
Description
ジオメトリ生成パスです。previewタスクにのみ適用されます。このパラメータを指定してrefineを行うと 400 が返されます。
利用可能な値:
- standard
- 2k: Ultraパスを2048³で実行
- 4k: Ultraパスを4096³で実行し、より精細な表面ディテールを生成
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 から 300000 30000
meshy-t2 100 から 15000 4000
meshy-t2.5 100 から 30000 15000
範囲外の値を指定すると 400 が返されます。

ケース	範囲	デフォルト
リメッシュ	`100` から `300000`	`30000`
`meshy-t2`	`100` から `15000`	`4000`
`meshy-t2.5`	`100` から `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ 非推奨
デフォルト auto
Description
指定しないでください。このパラメータは出力に影響しません。
利用可能な値:
- off: 対称を無効にする
- auto: 入力ジオメトリに基づいて対称を適用する
- on: 生成時に対称を強制する
Name
pose_mode
Type
string
デフォルト ""
Description
生成されるモデルのポーズです。
利用可能な値:
- a-pose: Aポーズ
- t-pose: Tポーズ
- ""（空文字列）: 特定のポーズなし
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が長すぎる: prompt が文字数制限を超えている。
- Ultraでサポートされていないモデル: geometry_resolution が 2k または 4k で、それを実行できない ai_model が指定されている。
リクエストを修正してから、再度送信してください。エラーを参照してください。
Name
401 - Unauthorized
Description
APIキーが欠落しているか無効です。Authorization ヘッダーを確認してください。
Name
402 - Payment Required
Description
例:
- クレジット不足: アカウントにこのタスクを実行するための十分なクレジットがない、またはアカウントがクレジット上限に達している。クレジット残高を確認してから再試行してください。
- 無料プラン: タスクの作成には有料プランが必要です。サブスクリプション設定でプランをアップグレードしてから再試行してください。
Name
429 - Too Many Requests
Description
レート制限を超えました。しばらく待ってから再試行してください。レート制限を参照してください。

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

Create a Text to 3D refine task

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
}'

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マップ（metallic、roughness、normal）も生成するかどうかです。
ai_model が meshy-6 の場合、Meshyはemissionマップも生成しますが、texture_resolution: 8k の場合は除きます。meshy-6-lite、meshy-7、meshy-7.1、latest ではemissionマップは生成されません。ai_model を指定していない meshy-t2 または meshy-t2.5 のpreviewのrefineでも生成されません。
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.1、または latest が必要です。8k の場合、Meshyはemissionマップを生成しません。
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 を使用します。
Name
texture_image_url
Type
string
Description
テクスチャ生成の指針となる2D画像で、公開URLまたはbase64エンコードされたデータURIとして指定します。例：data:image/jpeg;base64,<your base64-encoded image data>。
画像は .jpg、.jpeg、.png、または .webp ファイルで、最大20MBである必要があります。
画像内の形状がモデルと大きく異なる場合、画像からのテクスチャ適用がうまく機能しないことがあります。
Name
ai_model
Type
string
デフォルト inherited from the preview task
Description
メッシュにテクスチャを適用するAIモデルです。
利用可能な値：
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7（非推奨）：代わりに meshy-7.1 を送信してください
指定しない場合、previewタスクのモデルが使用され、previewとそのrefineが最初から最後まで同じモデルで実行されます。値を送信すると、それを上書きできます。明示的に latest を指定した場合も、previewタスクと同様に解決されるため、latest のpreviewとその latest のrefineは常に同じテクスチャモデルを使用します。
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.1 と latest はこれを受け付けますが無視します。ai_model を指定していない meshy-t2 または meshy-t2.5 のpreviewのrefineも同様です。meshy-6-lite と一緒に送信すると 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" と一緒に送信されました。
リクエストを修正してから、再度送信してください。エラーを参照してください。
Name
401 - Unauthorized
Description
APIキーが見つからないか無効です。Authorization ヘッダーを確認してください。
Name
402 - Payment Required
Description
例：
- Insufficient credits：アカウントにこのタスクを実行するのに十分なクレジットがないか、アカウントがクレジット上限に達しています。クレジット残高を確認してから、再試行してください。
- Free plan：タスクの作成には有料プランが必要です。サブスクリプション設定でプランをアップグレードしてから、再試行してください。
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": {

    "message": ""

  },

  "consumed_credits": 20
}

パラメータ

Name
id
Type
path
Description
作成レスポンスから取得したタスクIDです。

戻り値

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

例

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

Mode	サンプルモデル
Preview
Refine

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": {

      "message": ""

    },

    "consumed_credits": 20
  }
]

パラメータ

Name
page_num
Type
integer
デフォルト 1
Description
返すページ番号。
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": {

  "message": ""

},

"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タスクオブジェクトは、テキストのpromptから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": {

    "message": ""

  },

  "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ステージでのテクスチャリングを指示するために送信したテキストprompt。
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
video_url
Type
string
⚠ 非推奨
Description
将来のリリースで削除されるフィールドのため、このフィールドに依存しないでください。previewビデオのダウンロード用URL。
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
タスクが失敗した場合のエラー詳細。エラーを参照してください。
Name
consumed_credits
Type
integer
Description
タスクで使用されたクレジットの数。ステータスがPENDING、IN_PROGRESS、SUCCEEDEDのいずれかの場合に存在します。タスクが失敗すると、Meshyはクレジットを払い戻すため、FAILEDタスクの場合は0になります。