Relief API

Omvandla ett foto till en basrelief-3D-modell och en 16-bitars djupkarta, för 3D-utskrift, lasergravyr och CNC-fräsning.

POST/openapi/v1/relief

Skapa en Relief-uppgift

Skapar en Relief-uppgift. Uppgiften omvandlar ett foto till en basrelief-modell. När den lyckas skapar uppgiften modellen som en GLB-fil och en STL-fil, en 16-bitars gråskale-djupkarta samt en förhandsgranskningsbild. För att bara få djupkartan, sätt should_generate_model till false.

Uppgiften körs i bakgrunden.

En Relief-uppgift kan inte vara indata till en annan endpoint, såsom Remesh, Konvertera eller Auto Split. Sådana förfrågningar returnerar 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"
}

Parametrar

Name
image_url
Type
string
Obligatorisk
Description
Fotot som ska omvandlas till en relief, som en offentlig URL eller en data-URI (data:image/png;base64,...).
Bilden måste vara en JPG-, JPEG-, PNG- eller WebP-fil på högst 20 MB, och minst 32 × 32 pixlar. Dess längre sida kan vara som mest ungefär 16 gånger dess kortare sida. Alla andra bilder returnerar 400. Meshy fyller transparenta områden med svart innan reliefen byggs.
Name
variant
Type
string
standard low
Description
Relief-stilen. Den formar djupkartan och sätter standardvärdet för carving_depth_mm.
Tillgängliga värden:
- high: djupare ingravering, för 3D-utskrivna delar.
- low: grund ingravering, för laserkgravering, CNC-gravering och tunna plaketter.
Att skicka null eller "" är detsamma som att utelämna den. Alla andra värden returnerar 400.
Name
should_generate_model
Type
boolean
standard true
Description
Om reliefmodellen ska byggas. Sätt den till false för en uppgift som bara ger en djupkarta, utan modell och utan förhandsgranskningsbild. Meshy kontrollerar ändå storleks-, ingraverings-, bas-, böjnings- och upplösningsparametrarna, men använder dem inte. Det ändrar inte credit-kostnaden.

Name
size_mm
Type
number
standard 60
Description
Längden på fotots längre sida på modellen, mätt platt före eventuell böjning, från 20 till 250 millimeter. Med remove_base kan modellen bli mindre.
Name
carving_mode
Type
string
standard emboss
Description
Om motivet sticker ut från plattan eller är inskuret i den.
Tillgängliga värden:
- emboss: de närmare delarna av fotot sticker ut.
- engrave: djupet är inverterat, så de närmare delarna skärs in.
Djupkartan är densamma i båda lägena.
Name
carving_depth_mm
Type
number
standard 6 (high), 3 (low)
Description
Hur djupt reliefen graveras, från 0 till 60 millimeter. Med remove_base satt till true ger 0 en tom modell. Uppgiften lyckas ändå och kostar 20 credits, och dess GLB- och STL-filer saknar geometri.

Name
remove_base
Type
boolean
standard false
Description
Om bakgrunden ska skäras bort och ingen baslagerplatta byggas. När den är true avgör removal_threshold vad som räknas som bakgrund. Meshy kontrollerar removal_threshold oavsett.

Gäller endast när remove_base = true

Name
removal_threshold
Type
number
standard 0.01
Description
Djupet under vilket Meshy skär bort bakgrunden, från 0.01 till 1, där djupkartan löper från 0 till 1. Ett högt värde kan skära bort hela reliefen och lämna en tom modell, vilket ändå lyckas och debiteras.

Name
base_thickness_mm
Type
number
standard 1, or 0 with remove_base
Description
Tjockleken på baslagerplattan, från 0.1 till 10 millimeter. När remove_base är true, utelämna den eller skicka 0.

Name
bend_mode
Type
string
standard off
Description
Om reliefen ska böjas, och åt vilket håll. När den inte är off formar bend_axis och bend_angle böjningen. Meshy kontrollerar dem oavsett.
Tillgängliga värden:
- off: en platt relief.
- convex: framsidan buktar utåt.
- concave: framsidan böjer sig inåt.

Gäller endast när bend_mode = convex or concave

Name
bend_axis
Type
string
standard xz
Description
Vilka kanter böjningen kröker.
Tillgängliga värden:
- xz: vänster och höger kant.
- yz: övre och nedre kant.
Name
bend_angle
Type
number
standard 60
Description
Bågen böjningen spänner över, från 0 till 360 grader. Under 1 förblir reliefen platt.

Name
mesh_resolution
Type
integer
standard 1024
Description
Antalet nätpunkter längs fotots längre sida, från 512 till 2048. Ett högre värde bevarar finare detaljer och ger större filer. Vid standardvärdet 1024 är GLB-filen cirka 40 till 50 MB och STL-filen cirka 80 till 105 MB. Ett kvadratiskt foto ger de större storlekarna. Vid 2048 är de cirka 150 MB respektive 300 MB. En böjning gör dem större: STL-filen kan nå cirka 800 MB vid 2048.

Returnerar

202 Accepted, med ID:t för den nya Relief-uppgiften i result.

Felscenarier

Name
400 - Bad Request
Description
Förfrågan kan inte köras. Felmeddelandet anger vilket problem som hittades. Till exempel:
- Saknad parameter: image_url skickades inte.
- Ogiltig parameter: En parameter har fel typ, ligger utanför sitt intervall, eller är inte ett av dess tillgängliga värden. Till exempel är variant varken high eller low, eller mesh_resolution är inte ett heltal från 512 till 2048.
- Bastjocklek: base_thickness_mm är inte 0 med remove_base satt till true, eller är under 0.1 utan det.
- Onåbar URL: Meshy kan inte ladda ner bilden från image_url, till exempel för att URL:en returnerar 404 eller tidsgränsen överskrids.
- Ogiltig bild: Bilden är inte en JPG-, JPEG-, PNG- eller WebP-fil, är över 20 MB, är mindre än 32 × 32 pixlar, har för många pixlar, eller kan inte läsas.
- Extremt bildformat: Bildens längre sida är mer än ungefär 16 gånger dess kortare sida.
Åtgärda förfrågan och skicka den igen. Meshy debiterar inte för den. Se Fel.
Name
401 - Unauthorized
Description
API-nyckeln saknas eller är ogiltig. Kontrollera Authorization-headern.
Name
402 - Payment Required
Description
Till exempel:
- Otillräckliga credits: Kontot har inte tillräckligt med credits för den här uppgiften, eller kontot har nått en credit-gräns. Kontrollera ditt credit-saldo och försök sedan igen.
- Gratisplan: Att skapa en uppgift kräver en betalplan. Uppgradera din plan i dina prenumerationsinställningar och försök sedan igen.
Name
403 - Forbidden
Description
Innehållsmoderering blockerade bilden. Meshy debiterar inte för förfrågan. Skicka en annan bild.
Name
429 - Too Many Requests
Description
En av dessa gränser nåddes:
- Du skickade för många förfrågningar. Vänta och försök sedan igen. Se Hastighetsbegränsningar.
- För många av dina uppgifter är köade eller pågående. Vänta tills några är klara och försök sedan igen.
- På en obegränsad plan utan credits kvar har du nått antalet uppgifter som kan köras utan credits. Vänta tills en uppgift är klar, eller fyll på med credits.

Om en säkerhetskontroll avvisar bilden medan uppgiften körs, misslyckas uppgiften med task_error.type satt till invalid_input och task_error.code satt till provider_content_refused. Meshy återbetalar uppgiftens credits. Skicka en annan bild. Se Fel.

GET/openapi/v1/relief/:id

Hämta en Relief-uppgift

Returnerar en Relief-uppgift baserat på dess ID.

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
}

Parametrar

Name
id
Type
path
Description
Uppgifts-ID:t från skaparsvaret.

Returnerar

Relief-uppgiftsobjektet.

DELETE/openapi/v1/relief/:id

Ta bort en Relief-uppgift

Tar permanent bort en Relief-uppgift, inklusive dess modell, djupkarta och data. Du kan inte ångra en borttagning.

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."
}

Sökvägsparametrar

Name
id
Type
path
Description
ID:t för uppgiften som ska tas bort.

Uppgiftsstatus

Om du tar bort en PENDING-uppgift återbetalas de credits som användes när du skapade den.

En IN_PROGRESS-uppgift kan inte tas bort. Begäran returnerar 409 Conflict, och uppgiften fortsätter att köras. Meshy återbetalar inte en uppgift som har påbörjats, så att ta bort den skulle kosta dig både credits och resultatet. Vänta tills den når SUCCEEDED eller FAILED, och ta sedan bort den.

Om du tar bort en SUCCEEDED-uppgift återbetalas inte dess credits. En FAILED-uppgift återbetalades redan när den misslyckades.

Returnerar

200 OK när uppgiften har tagits bort, eller 409 Conflict när uppgiften är IN_PROGRESS.

GET/openapi/v1/relief

Lista Relief-uppgifter

Returnerar en lista över dina Relief-uppgifter.

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

Parametrar

Name
page_num
Type
integer
Description
Sidnumret som ska returneras. Börjar på och har som standard 1.
Name
page_size
Type
integer
Description
Antalet uppgifter per sida, upp till 100. Standardvärdet är 10. Meshy behandlar ett värde från 101 till 255 som 100, och ett större värde returnerar 400.
Name
sort_by
Type
string
Description
Sorteringsordningen.
Tillgängliga värden:
- +created_at: äldsta först
- -created_at: nyaste först

Returnerar

En paginerad lista med Relief-uppgiftsobjekt.

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

Streama en Relief-uppgift

Streamar uppdateringar för en Relief-uppgift som 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
}

Parametrar

Name
id
Type
path
Description
Uppgifts-ID från skaparens svar.

Returnerar

En ström av Relief-uppgiftsobjekt som Server-Sent Events.

Varje message-händelse innehåller hela uppgiftsobjektet, samma som Hämta en Relief-uppgift returnerar. Medan uppgiften är PENDING eller IN_PROGRESS är det fälten progress, status, started_at och preceding_tasks (finns bara medan det finns uppgifter före denna) som ändras mellan händelser. model_urls, depth_map_url och thumbnail_url får sina värden när uppgiften når SUCCEEDED. En uppgift som bara gäller djupkarta behåller model_urls {} och en tom thumbnail_url.

En error-händelse innehåller endast status_code och message, så kontrollera händelsenamnet innan du läser status.

Relief-uppgiftsobjektet

Ett Relief-uppgiftsobjekt beskriver en relief skapad från ett foto. model_urls, depth_map_url och thumbnail_url finns alltid med, och är tomma tills uppgiften lyckas.

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
Uppgifts-ID:t. Behandla det som en opak sträng och förlita dig inte på dess format.
Name
type
Type
string
Description
Uppgiftstypen, alltid relief.
Name
model_urls
Type
object
Description
Nedladdnings-URL:er för reliefmodellen. Filerna kan vara stora; mesh_resolution listar typiska storlekar.
- Name
  glb
  Type
  string
  Description
  GLB-filen, utan textur. Dess enheter är meter. Saknas för en uppgift som enbart genererar djupkarta.
- Name
  stl
  Type
  string
  Description
  Samma modell som en binär STL-fil. Dess enheter är millimeter, så den öppnas i reliefens verkliga storlek, med Z uppåt. Saknas för en uppgift som enbart genererar djupkarta.
Name
depth_map_url
Type
string
Description
Nedladdnings-URL för den 16-bitars gråskale-djupkarta som reliefen byggs från. Ljusare pixlar är högre. Värdena är relativa höjder, inte millimeter. Mjukvara för lasergravering och CNC kan använda den som en höjdkarta. Filen är ungefär 1 till 2 MB. Tom om ingen finns.
Name
thumbnail_url
Type
string
Description
Nedladdnings-URL för en förhandsgranskningsbild av reliefmodellen. Tom om ingen renderades, inklusive för en uppgift som enbart genererar djupkarta.
Name
progress
Type
integer
Description
Hur mycket av uppgiften som är klar, i procent. Den är 0 tills uppgiften startar och 100 när den lyckas.
Name
status
Type
string
Description
Uppgiftens status, en av PENDING, IN_PROGRESS, SUCCEEDED eller FAILED.
Name
preceding_tasks
Type
integer
Description
Antalet uppgifter före denna i kön. Fältet utelämnas när värdet är 0, så det visas endast medan det finns uppgifter före denna.
Name
created_at
Type
timestamp
Description
Tidpunkt då uppgiften skapades, i Unix-millisekunder.
Name
started_at
Type
timestamp
Description
Tidpunkt då uppgiften startade, i Unix-millisekunder. Den är 0 tills uppgiften startar.
Name
finished_at
Type
timestamp
Description
Tidpunkt då uppgiften avslutades, i Unix-millisekunder. Den är 0 tills uppgiften avslutas.
Name
expires_at
Type
timestamp
Description
Tidpunkt då uppgiftens resultat upphör att gälla, i Unix-millisekunder. Den är 0 tills uppgiften avslutas.
Name
task_error
Type
object
Description
Felinformationen när uppgiften misslyckas. Se Fel.
Name
consumed_credits
Type
integer
Description
Antalet credits som uppgiften använde: 20, eller 0 för en FAILED-uppgift, vilket Meshy återbetalar.