リテクスチャ API

Retexture API は、Meshy の AI リテクスチャ機能を自身のアプリケーションに統合できる機能です。このセクションでは、この API を使い始めるために必要なすべての情報を確認できます。

POST/openapi/v1/retexture

リテクスチャタスクを作成

この endpoint では、新しいリテクスチャタスクを作成できます。リテクスチャタスクオブジェクトに含まれるプロパティについては、リテクスチャタスクオブジェクトを参照してください。

パラメータ

input_task_id または model_url のいずれか 1 つのみが必須です。両方が指定された場合、input_task_id が優先されます。

Name
input_task_id
Type
string
必須
Description
リテクスチャしたい、完了済みの Image to 3D または Text to 3D タスクの ID。このタスクは、Text to 3D Preview、Text to 3D Refine、Image to 3D、または Remesh のいずれかである必要があります。さらに、ステータスが SUCCEEDED である必要があります。

Name
model_url
Type
string
必須
Description
Meshy がテクスチャを適用する 3D モデルを指定します。対応形式: .glb、.gltf、.obj、.fbx、.stl。
モデルを指定する方法は 2 つあります。
- 公開アクセス可能な URL: パブリックインターネットからアクセス可能な URL。
- Data URI: モデルの base64 エンコードされたデータ URI。MIME タイプ application/octet-stream を使用します。例: data:application/octet-stream;base64,<your base64-encoded model data>。

text_style_prompt または image_style_url のいずれか 1 つのみが必須です。両方が指定された場合、image_style_url が優先されます。

Name
text_style_prompt
Type
string
必須
Description
オブジェクトに適用したいテクスチャスタイルをテキストで説明します。最大 600 文字。

Name
image_style_url
Type
string
必須
Description
テクスチャ生成プロセスのガイドとして使用する 2D 画像を指定します。現在、.jpg、.jpeg、.png 形式に対応しています。
画像を指定する方法は 2 つあります。
- 公開アクセス可能な URL: パブリックインターネットからアクセス可能な URL
- Data URI: 画像の base64 エンコードされたデータ URI。データ URI の例: data:image/jpeg;base64,<your base64-encoded image data>
元のアセットとアップロードされた画像の間に大きなジオメトリの違いがある場合、画像によるテクスチャ生成が最適に機能しないことがあります。

Name
ai_model
Type
string
デフォルト latest
Description
リテクスチャに使用する AI モデルの ID。利用可能な値: meshy-5、meshy-6、latest（Meshy 6）。
Name
enable_original_uv
Type
boolean
デフォルト false
Description
新しい UV レイアウトを生成する代わりに、モデルの既存の UV レイアウトを保持します。
- Meshy が生成したモデル（input_task_id 経由、または Meshy の出力を指す model_url）をリテクスチャする場合は、最適化された UV レイアウトを再利用するためにこれを true に設定します。
- アップロードしたサードパーティ製モデルをリテクスチャする場合、保持したい良好な UV が既にある場合は true に設定するか、適切な UV マッピングがないモデルに最適な新しい UV 展開を Meshy に行わせる場合は false のままにします。
Name
enable_pbr
Type
boolean
デフォルト false
Description
ベースカラーに加えて、PBR マップ（メタリック、ラフネス、ノーマル）を生成します。ai_model が meshy-6 または latest の場合は、エミッションマップも含まれます。
Name
hd_texture
Type
boolean
デフォルト false
Description
より高いディテールのために、ベースカラーテクスチャを 4K（4096×4096）解像度で生成します。
ai_model が meshy-6 または latest の場合にのみ対応しています。PBR マップは常に 2K で生成されます。
Name
remove_lighting
Type
boolean
デフォルト true
Description
ベースカラーテクスチャからハイライトとシャドウを除去し、カスタムライティング設定でより適切に機能する、よりクリーンな結果を生成します。
ai_model が meshy-6 または latest の場合にのみ対応しています。
Name
target_formats
Type
string[]
Description
出力に含める 3D ファイル形式を指定します。リクエストされた形式のみが生成および返却されるため、タスク完了時間を短縮できます。省略した場合、対応しているすべての形式が含まれます。
利用可能な値: glb、obj、fbx、stl、usdz、3mf
省略した場合、3mf を除くすべての形式が生成されます。3mf は明示的に指定された場合にのみ含まれます。
Name
alpha_thumbnail
Type
boolean
デフォルト false
Description
true に設定すると、タスクはプレビューの透過背景（RGBA）版もレンダリングし、GET レスポンスで alpha_thumbnail_url として返します。既存の thumbnail_url フィールドは変更されません。

戻り値

レスポンスの result プロパティには、新しく作成されたリテクスチャタスクのタスク id が含まれます。

失敗モード

Name
400 - Bad Request
Description
リクエストは受け付けられませんでした。一般的な原因:
- パラメータ不足: model_url または input_task_id のいずれかを指定する必要があります。
- スタイル不足: text_style_prompt または image_style_url のいずれかを指定する必要があります。
- 無効な入力タスク: input_task_id は、対応モデルによる成功済みタスクを参照している必要があります。
- 無効なモデル形式: model_url が、対応していない拡張子のファイルを指しています。
- 到達不能な URL: model_url または image_style_url をダウンロードできませんでした。
Name
401 - Unauthorized
Description
認証に失敗しました。API key を確認してください。
Name
402 - Payment Required
Description
このタスクを実行するためのクレジットが不足しています。
Name
429 - Too Many Requests
Description
レート制限を超過しています。

Request

POST

/openapi/v1/retexture

# Retexture with text prompt
curl https://api.meshy.ai/openapi/v1/retexture \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "https://cdn.meshy.ai/model/example_model_2.glb",
    "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
    "enable_original_uv": true,
    "enable_pbr": true
  }'

# Retexture with image style and PBR
curl https://api.meshy.ai/openapi/v1/retexture \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "https://cdn.meshy.ai/model/example_model_2.glb",
    "image_style_url": "https://cdn.meshy.ai/image/example_image.jpg",
    "ai_model": "latest",
    "enable_pbr": true,
    "enable_original_uv": true
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/retexture/:id

Retextureタスクを取得

このendpointでは、有効なタスクidを指定してRetextureタスクを取得できます。 Retextureタスクオブジェクトに含まれるプロパティについては、 Retextureタスクオブジェクトを参照してください。

パラメーター

Name
id
Type
path
Description
取得するRetextureタスクの一意の識別子。

戻り値

レスポンスにはRetextureタスクオブジェクトが含まれます。詳細については、 Retextureタスクオブジェクトセクションを確認してください。

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "retexture",
  "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=***",
    "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=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
  "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"
    }
  ],
  "task_error": {

    "message": ""

  },

  "consumed_credits": 10
}

DELETE/openapi/v1/retexture/:id

Retextureタスクを削除

このendpointは、関連するすべてのモデルとデータを含むRetextureタスクを完全に削除します。この操作は元に戻せません。

パスパラメータ

Name
id
Type
path
Description
削除するRetextureタスクのID。

戻り値

成功時に 200 OK を返します。

Request

DELETE

/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/retexture

リテクスチャタスクの一覧

この endpoint では、リテクスチャタスクの一覧を取得できます。

パラメータ

Name
page_num
Type
integer
デフォルト 1
Description
ページネーションのページ番号。
Name
page_size
Type
integer
デフォルト 10
Description
ページサイズの上限。許可される最大値は 50 件です。
Name
sort_by
Type
string
Description
ソート対象のフィールド。
利用可能な値:
- +created_at: 作成時刻の昇順でソートします。
- -created_at: 作成時刻の降順でソートします。

戻り値

リテクスチャタスクオブジェクトのページネーションされた一覧を返します。

Request

GET

/openapi/v1/retexture

curl https://api.meshy.ai/openapi/v1/retexture?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "retexture",
    "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=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
    "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": {

      "message": ""

    },

    "consumed_credits": 10
  }
]

GET/openapi/v1/retexture/:id/stream

リテクスチャタスクをストリーミングする

この endpoint は、Server-Sent Events (SSE) を使用してリテクスチャタスクのリアルタイム更新をストリーミングします。

パラメータ

Name
id
Type
path
Description
ストリーミングするリテクスチャタスクの一意の識別子。

戻り値

Server-Sent Events としてリテクスチャタスクオブジェクトのストリームを返します。

PENDING または IN_PROGRESS のタスクの場合、レスポンスストリームには必要な progress と status フィールドのみが含まれます。

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/retexture/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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": "retexture",
  "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=***",
    "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=***",
    "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=***"
  },
  "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": 10
}

Retextureタスクオブジェクト

Retextureタスクオブジェクトは、Meshyがテキストまたは画像入力から3Dテクスチャを生成するために使用する作業単位です。このモデルには次のプロパティがあります:

プロパティ

Name
id
Type
string
Description
タスクの一意の識別子です。実装の詳細としてタスクIDにはkソート可能なUUIDを使用していますが、 idの形式についてはいかなる仮定も行わないでください。
Name
type
Type
string
Description
Retextureタスクの種類です。値はretextureです。
Name
model_urls
Type
object
Description
Meshyによって生成された、テクスチャ付き3Dモデルファイルのダウンロード可能なURLです。
- Name
  glb
  Type
  string
  Description
  GLBファイルのダウンロード可能なURLです。
- Name
  fbx
  Type
  string
  Description
  FBXファイルのダウンロード可能なURLです。
- Name
  obj
  Type
  string
  Description
  OBJファイルのダウンロード可能なURLです。
- Name
  usdz
  Type
  string
  Description
  USDZファイルのダウンロード可能なURLです。
- Name
  mtl
  Type
  string
  Description
  MTLファイルのダウンロード可能なURLです。テクスチャが存在する場合、OBJエクスポートとともに返されます。
- Name
  stl
  Type
  string
  Description
  STLファイルのダウンロード可能なURLです。
- Name
  3mf
  Type
  string
  Description
  3MFファイルのダウンロード可能なURLです。target_formatsを介して3mfがリクエストされた場合にのみ存在します。
Name
text_style_prompt
Type
string
Description
これはテクスチャリングタスクの作成に使用されたテキストプロンプトです。
Name
image_style_url
Type
string
Description
これはテクスチャリングタスクの作成に使用された画像入力です。
Name
thumbnail_url
Type
string
Description
モデルファイルのサムネイル画像のダウンロード可能なURLです。
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_urlの透明背景（RGBA）バージョンのダウンロード可能なURLです。タスクがalpha_thumbnail: trueで作成され、透明プレビューが正常にレンダリングされた場合にのみ存在します。それ以外の場合、このフィールドは省略されます。
Name
progress
Type
integer
Description
タスクの進捗です。タスクがまだ開始されていない場合、このプロパティは0になります。タスクが成功すると、100になります。
Name
started_at
Type
timestamp
Description
タスクが開始された時刻のタイムスタンプ（ミリ秒）です。タスクがまだ開始されていない場合、このプロパティは0になります。
タイムスタンプは、RFC 3339標準に従い、 1970年1月1日 UTCから経過したミリ秒数を表します。たとえば、2023年9月1日（金）12:00:00 PM GMTは1693569600000として表されます。これはMeshy API内のすべてのタイムスタンプに適用されます。
Name
created_at
Type
timestamp
Description
タスクが作成された時刻のタイムスタンプ（ミリ秒）です。
Name
expires_at
Type
timestamp
Description
タスク結果の有効期限のタイムスタンプ（ミリ秒）です。
Name
finished_at
Type
timestamp
Description
タスクが完了した時刻のタイムスタンプ（ミリ秒）です。タスクがまだ完了していない場合、このプロパティは0になります。
Name
status
Type
string
Description
タスクのステータスです。可能な値はPENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELEDのいずれかです。
Name
texture_urls
Type
array
Description
タスクから生成されるテクスチャURLオブジェクトの配列です。通常、これにはテクスチャURLオブジェクトが1つだけ含まれます。各テクスチャURLには次のプロパティがあります。
- 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です。
  タスクがenable_pbr: falseで作成された場合、またはai_modelがmeshy-5の場合、このプロパティは省略されます。
Name
preceding_tasks
Type
integer
Description
先行タスクの数です。
このプロパティは、タスクのステータスがPENDINGの場合にのみ表示されます。
Name
task_error
Type
object
Description
失敗したタスクのエラー詳細です。完全なtask_errorオブジェクトのリファレンスについては、エラーを参照してください。
Name
consumed_credits
Type
integer
Description
このタスクによって消費されたクレジット数です。タスクのステータスがPENDING、IN_PROGRESS、またはSUCCEEDEDの場合に存在します。FAILEDタスクの場合は0を返します（失敗時にはクレジットが返還されます）。

Example Retexture Task Model

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "retexture",
  "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=***"
  },
  "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
  "image_style_url": "https://assets.meshy.ai/***/image/example_image.jpg?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "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": {

    "message": ""

  },

  "consumed_credits": 10
}