レリーフ API

1枚の写真を、3Dプリント、レーザー彫刻、CNC切削に使える浮き彫り（バスレリーフ）3Dモデルと16ビットの深度マップに変換します。

POST/openapi/v1/relief

Relief タスクを作成する

Relief タスクを作成します。このタスクは写真を浮き彫り（レリーフ）モデルに変換します。成功すると、タスクはモデルをGLBファイルとSTLファイル、16ビットのグレースケール深度マップ、プレビュー画像として生成します。深度マップのみを取得するには、should_generate_model を false に設定してください。

タスクはバックグラウンドで実行されます。

Relief タスクは、Remesh、Convert、Auto Split などの他のエンドポイントの入力にすることはできません。これらのリクエストは 403 を返します。

Request

POST

/openapi/v1/relief

# Simple request: a low relief, 60 mm on its longer side
curl https://api.meshy.ai/openapi/v1/relief \
-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>"
  }'

# Advanced request: a deep 120 mm relief with a thicker base, curved from side to side
curl https://api.meshy.ai/openapi/v1/relief \
-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>",
    "variant": "high",
    "size_mm": 120,
    "carving_depth_mm": 10,
    "base_thickness_mm": 3,
    "bend_mode": "convex",
    "bend_angle": 90
  }'

Response

{
  "result": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20"
}

パラメータ

Name
image_url
Type
string
必須
Description
レリーフに変換する写真。公開URLまたはData URI（data:image/png;base64,...）として指定します。
画像はJPG、JPEG、PNG、またはWebPファイルで、最大20MB、最小32×32ピクセルである必要があります。長辺は短辺の約16倍までです。それ以外の画像は 400 を返します。Meshyはレリーフを作成する前に、透明な領域を黒で塗りつぶします。
Name
variant
Type
string
デフォルト low
Description
レリーフのスタイル。深度マップの形状を決め、carving_depth_mm のデフォルト値を設定します。
使用可能な値：
- high：深い彫り込み。3Dプリント部品向け。
- low：浅い彫り込み。レーザー彫刻、CNC彫刻、薄いプレート向け。
null または "" を送信することは、省略した場合と同じです。それ以外の値は 400 を返します。
Name
should_generate_model
Type
boolean
デフォルト true
Description
レリーフモデルを生成するかどうか。深度マップのみのタスク（モデルもプレビュー画像も生成しない）にするには false に設定します。Meshyはサイズ、彫り込み、ベース、ベンド、解像度の各パラメータを引き続きチェックしますが、それらは使用しません。クレジットのコストは変わりません。

Name
size_mm
Type
number
デフォルト 60
Description
モデル上での写真の長辺の長さ。ベンド前のフラットな状態で測定し、20 から 250 ミリメートルの範囲です。remove_base を使用すると、モデルをより小さくできます。
Name
carving_mode
Type
string
デフォルト emboss
Description
被写体をプレートから浮き立たせるか、プレートに彫り込むかを指定します。
使用可能な値：
- emboss：写真の手前側の部分が浮き出ます。
- engrave：深度が反転し、手前側の部分が彫り込まれます。
深度マップはどちらのモードでも同じです。
Name
carving_depth_mm
Type
number
デフォルト 6 (high), 3 (low)
Description
レリーフをどれだけ深く彫り込むか。0 から 60 ミリメートルの範囲です。remove_base が true に設定されている場合、0 にすると空のモデルになります。タスクは成功し、20クレジットが課金されますが、生成されるGLBファイルとSTLファイルにはジオメトリがありません。

Name
remove_base
Type
boolean
デフォルト false
Description
背景を切り取り、ベースプレートを作成しないかどうか。true の場合、removal_threshold が背景とみなす基準を設定します。Meshyはどちらの場合でも removal_threshold をチェックします。

次の場合のみ適用 remove_base = true

Name
removal_threshold
Type
number
デフォルト 0.01
Description
Meshyが背景を切り取る深度のしきい値。0.01 から 1 の範囲で、深度マップは 0 から 1 までの範囲です。高い値を設定すると、レリーフ全体が切り取られて空のモデルになることがありますが、それでもタスクは成功し課金されます。

Name
base_thickness_mm
Type
number
デフォルト 1, or 0 with remove_base
Description
ベースプレートの厚さ。0.1 から 10 ミリメートルの範囲です。remove_base が true の場合、省略するか 0 を送信してください。

Name
bend_mode
Type
string
デフォルト off
Description
レリーフを曲げるかどうか、およびどの方向に曲げるか。off 以外の場合、bend_axis と bend_angle が曲げの形状を決めます。Meshyはどちらの場合でもこれらをチェックします。
使用可能な値：
- off：平らなレリーフ。
- convex：正面が外側に膨らみます。
- concave：正面が内側に湾曲します。

次の場合のみ適用 bend_mode = convex or concave

Name
bend_axis
Type
string
デフォルト xz
Description
どの端を曲げの起点にするか。
使用可能な値：
- xz：左右の端。
- yz：上下の端。
Name
bend_angle
Type
number
デフォルト 60
Description
曲げが広がる弧の角度。0 から 360 度の範囲です。1 未満の場合、レリーフは平らなままです。

Name
mesh_resolution
Type
integer
デフォルト 1024
Description
写真の長辺に沿ったメッシュポイントの数。512 から 2048 の範囲です。値が大きいほど細部の精度が保たれ、ファイルサイズも大きくなります。デフォルトの 1024 では、GLBファイルは約40〜50MB、STLファイルは約80〜105MBになります。正方形の写真の場合はより大きいサイズになります。2048 では、それぞれ約150MBと300MBになります。ベンドを加えると、さらにサイズが大きくなります。2048 ではSTLファイルが約800MBに達することがあります。

戻り値

202 Accepted。新しいRelief タスクのIDが result に含まれます。

失敗モード

Name
400 - Bad Request
Description
リクエストを実行できません。エラーメッセージには、どの問題が検出されたかが示されます。例：
- パラメータの欠落：image_url が送信されませんでした。
- 無効なパラメータ：パラメータの型が誤っている、範囲外である、または使用可能な値のいずれでもありません。例えば、variant が high でも low でもない、または mesh_resolution が 512 から 2048 の整数ではない場合です。
- ベースの厚さ：remove_base が true に設定されている場合に base_thickness_mm が 0 でない、または設定されていない場合に 0.1 未満である場合です。
- 到達不能なURL：Meshyが image_url の画像をダウンロードできません。例えば、URLが 404 を返す、またはタイムアウトする場合です。
- 無効な画像：画像がJPG、JPEG、PNG、またはWebPファイルでない、20MBを超えている、32×32ピクセルより小さい、ピクセル数が多すぎる、または読み込めない場合です。
- 極端なアスペクト比：画像の長辺が短辺の約16倍を超えています。
リクエストを修正してから、再度送信してください。Meshyはこれに対して課金しません。エラーを参照してください。
Name
401 - Unauthorized
Description
APIキーが欠落しているか無効です。Authorization ヘッダーを確認してください。
Name
402 - Payment Required
Description
例：
- クレジット不足：アカウントにこのタスクを実行するための十分なクレジットがない、またはアカウントがクレジット制限に達しています。クレジット残高を確認してから、再試行してください。
- 無料プラン：タスクの作成には有料プランが必要です。サブスクリプション設定でプランをアップグレードしてから、再試行してください。
Name
403 - Forbidden
Description
コンテンツのmoderationによって画像がブロックされました。Meshyはこのリクエストに対して課金しません。別の画像を送信してください。
Name
429 - Too Many Requests
Description
次のいずれかの制限に達しました：
- リクエストを送信しすぎました。しばらく待ってから再試行してください。レート制限を参照してください。
- キューに入っているか実行中のタスクが多すぎます。いくつか完了するのを待ってから再試行してください。
- クレジットが残っていない無制限プランで、クレジットなしで実行できるタスク数の上限に達しました。タスクが完了するのを待つか、クレジットを追加してください。

タスクの実行中に安全性チェックによって画像が拒否された場合、タスクは失敗し、task_error.type が invalid_input に、task_error.code が provider_content_refused に設定されます。Meshyはタスクのクレジットを返金します。別の画像を送信してください。エラーを参照してください。

GET/openapi/v1/relief/:id

Relief タスクを取得

IDを指定してRelief タスクを返します。

Request

GET

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20

curl https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

パラメータ

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

戻り値

Relief タスクオブジェクト。

DELETE/openapi/v1/relief/:id

Relieフタスクを削除する

Reliefタスクを完全に削除します。モデル、深度マップ、データも含めて削除され、元に戻すことはできません。

Request

DELETE

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
  -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 になるまで待ってから削除してください。

SUCCEEDED のタスクを削除してもクレジットは返金されません。FAILED のタスクは失敗した時点ですでに返金済みです。

戻り値

タスクが削除された場合は 200 OK、タスクが IN_PROGRESS の場合は 409 Conflict を返します。

GET/openapi/v1/relief

レリーフタスクの一覧取得

あなたのレリーフタスクの一覧を返します。

Request

GET

/openapi/v1/relief

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

Response

[
  {
    "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
    "type": "relief",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
    },
    "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000060000,
    "expires_at": 1700259260000,
    "task_error": null,
    "consumed_credits": 20
  }
]

パラメータ

Name
page_num
Type
integer
Description
返すページ番号。1 から始まり、デフォルトは 1 です。
Name
page_size
Type
integer
Description
1ページあたりのタスク数（最大 100）。デフォルトは 10 です。Meshy は 101 から 255 までの値を 100 として扱い、それより大きい値の場合は 400 を返します。
Name
sort_by
Type
string
Description
並び順。
利用可能な値:
- +created_at: 古い順
- -created_at: 新しい順

返り値

レリーフタスクオブジェクトのページネーションされたリスト。

GET/openapi/v1/relief/:id/stream

Relieftaskをストリーミングする

Reliefタスクの更新情報をServer-Sent Events（SSE）としてストリーミングします。

Request

GET

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/stream

curl -N https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/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 (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

パラメータ

Name
id
Type
path
Description
作成リクエストのレスポンスで返されたタスクID。

戻り値

ReliefタスクオブジェクトのストリームがServer-Sent Eventsとして返されます。

各messageイベントには、Reliefタスクを取得するが返すものと同じ、タスクオブジェクト全体が含まれます。タスクがPENDINGまたはIN_PROGRESSの間、イベントごとに変化するフィールドはprogress、status、started_at、およびpreceding_tasks（このタスクより前に処理待ちのタスクがある間のみ存在）です。model_urls、depth_map_url、thumbnail_urlは、タスクがSUCCEEDEDに達した時点で値が設定されます。深度マップのみのタスクでは、model_urlsは{}のまま、thumbnail_urlは空のままになります。

errorイベントにはstatus_codeとmessageのみが含まれるため、statusを読む前にイベント名を確認してください。

Relief タスクオブジェクト

Relief タスクオブジェクトは、1枚の写真から作成されたレリーフを表します。model_urls、depth_map_url、thumbnail_url は常に存在し、タスクが成功するまでは空です。

The Relief Task Object

{
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Depth map only

{
  "id": "0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31",
  "type": "relief",
  "model_urls": {},
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31/output/depth.png?Expires=***",
  "thumbnail_url": "",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1700259230000,
  "task_error": null,
  "consumed_credits": 20
}

Name
id
Type
string
Description
タスクID。不透明な文字列として扱い、その形式に依存しないでください。
Name
type
Type
string
Description
タスクタイプ。常に relief です。
Name
model_urls
Type
object
Description
レリーフモデルのダウンロードURL。ファイルは大きくなることがあります。一般的なサイズについては mesh_resolution を参照してください。
- Name
  glb
  Type
  string
  Description
  テクスチャなしのGLBファイル。単位はメートルです。深度マップのみのタスクでは存在しません。
- Name
  stl
  Type
  string
  Description
  同じモデルのバイナリSTLファイル。単位はミリメートルなので、Zを上にしてレリーフの実際のサイズで開きます。深度マップのみのタスクでは存在しません。
Name
depth_map_url
Type
string
Description
レリーフの元になった16ビットグレースケール深度マップのダウンロードURL。明るいピクセルほど高くなります。値は相対的な高さであり、ミリメートルではありません。レーザー彫刻やCNCソフトウェアで高さマップとして使用できます。ファイルサイズは約1〜2MBです。存在しない場合は空です。
Name
thumbnail_url
Type
string
Description
レリーフモデルのプレビュー画像のダウンロードURL。深度マップのみのタスクを含め、レンダリングされなかった場合は空です。
Name
progress
Type
integer
Description
タスクの完了度をパーセンテージで示します。タスクが開始するまでは 0 で、成功すると 100 になります。
Name
status
Type
string
Description
タスクのステータス。PENDING、IN_PROGRESS、SUCCEEDED、FAILED のいずれかです。
Name
preceding_tasks
Type
integer
Description
このタスクより前にキュー内にあるタスクの数。値が 0 の場合、このフィールドは省略されるため、このタスクより前にタスクがある間のみ表示されます。
Name
created_at
Type
timestamp
Description
タスクが作成された時刻（Unixミリ秒）。
Name
started_at
Type
timestamp
Description
タスクが開始した時刻（Unixミリ秒）。タスクが開始するまでは 0 です。
Name
finished_at
Type
timestamp
Description
タスクが終了した時刻（Unixミリ秒）。タスクが終了するまでは 0 です。
Name
expires_at
Type
timestamp
Description
タスクの結果が期限切れになる時刻（Unixミリ秒）。タスクが終了するまでは 0 です。
Name
task_error
Type
object
Description
タスクが失敗した場合のエラー詳細。エラーを参照してください。
Name
consumed_credits
Type
integer
Description
タスクが使用したクレジット数：20、または FAILED タスクの場合は 0 で、この場合Meshyが返金します。