API för Omtexturering

API för Omtexturering är en funktion som gör det möjligt för dig att integrera Meshys AI-funktioner för omtexturering i din egen applikation. I det här avsnittet hittar du all information du behöver för att komma igång med detta API.

POST/openapi/v1/retexture

Skapa en Omtexturering-uppgift

Denna endpoint låter dig skapa en ny Omtexturering-uppgift. Se Omtexturering-uppgiftsobjektet för att se vilka egenskaper som ingår i Omtexturering-uppgiftsobjektet.

Parametrar

Endast en av input_task_id eller model_url krävs. Om båda anges har input_task_id prioritet.

Name
input_task_id
Type
string
Obligatorisk
Description
ID:t för den slutförda Bild till 3D- eller Text till 3D-uppgiften som du vill omtexturera. Denna uppgift måste vara en av följande uppgifter: Text till 3D Preview, Text till 3D Refine, Bild till 3D eller Remesh. Dessutom måste den ha statusen SUCCEEDED.

Name
model_url
Type
string
Obligatorisk
Description
Tillhandahåll en 3D-modell som Meshy ska texturera. Format som stöds: .glb, .gltf, .obj, .fbx, .stl.
Det finns två sätt att tillhandahålla modellen:
- Publikt tillgänglig URL: En URL som är tillgänglig från det publika internet.
- Data URI: En base64-kodad Data URI för modellen. Använd MIME type application/octet-stream. Exempel: data:application/octet-stream;base64,<your base64-encoded model data>.

Endast en av text_style_prompt eller image_style_url krävs. Om båda anges har image_style_url prioritet.

Name
text_style_prompt
Type
string
Obligatorisk
Description
Beskriv objektets önskade texturstil med text. Maximalt 600 tecken.

Name
image_style_url
Type
string
Obligatorisk
Description
Tillhandahåll en 2D-bild för att vägleda textureringsprocessen. Vi stöder för närvarande formaten .jpg, .jpeg och .png.
Det finns två sätt att tillhandahålla bilden:
- Publikt tillgänglig URL: En URL som är tillgänglig från det publika internet
- Data URI: En base64-kodad Data URI för bilden. Exempel på en Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Bildtexturering kanske inte fungerar optimalt om det finns betydande geometri-skillnader mellan den ursprungliga asseten och den uppladdade bilden.

Name
ai_model
Type
string
standard latest
Description
ID för AI-modellen som ska användas för omtexturering. Tillgängliga värden: meshy-5, meshy-6, latest (Meshy 6).
Name
enable_original_uv
Type
boolean
standard false
Description
Behåll modellens befintliga UV-layout i stället för att generera en ny.
- Om du omtexturerar en modell som Meshy genererade (via input_task_id, eller en model_url som pekar på en Meshy-utdata), sätt detta till true för att återanvända dess optimerade UV-layout.
- Om du omtexturerar en tredjepartsmodell som du laddat upp, sätt true när den redan har bra UV:er som du vill behålla, eller lämna det som false för att låta Meshy packa upp nya UV:er (bäst för modeller som saknar korrekt UV-mappning).
Name
enable_pbr
Type
boolean
standard false
Description
Generera PBR-mappar (metallic, roughness, normal) utöver basfärgen. En emissionskarta ingår också när ai_model är meshy-6 eller latest.
Name
hd_texture
Type
boolean
standard false
Description
Generera basfärgtexturen i 4K-upplösning (4096×4096) för högre detaljrikedom.
Stöds endast när ai_model är meshy-6 eller latest. PBR-mappar genereras alltid i 2K.
Name
remove_lighting
Type
boolean
standard true
Description
Tar bort högdagrar och skuggor från basfärgtexturen, vilket ger ett renare resultat som fungerar bättre under anpassade ljussättningar.
Stöds endast när ai_model är meshy-6 eller latest.
Name
target_formats
Type
string[]
Description
Anger vilka 3D-filformat som ska inkluderas i utdatan. Endast de begärda formaten genereras och returneras, vilket kan minska tiden för uppgiftens slutförande. När detta utelämnas inkluderas alla format som stöds.
Tillgängliga värden: glb, obj, fbx, stl, usdz, 3mf
När detta utelämnas genereras alla format utom 3mf. 3mf inkluderas endast när det uttryckligen anges.
Name
alpha_thumbnail
Type
boolean
standard false
Description
När detta är satt till true renderar uppgiften dessutom en version av förhandsvisningen med transparent bakgrund (RGBA) och returnerar den som alpha_thumbnail_url i GET-svaret. Det befintliga fältet thumbnail_url ändras inte.

Returnerar

Egenskapen result i svaret innehåller uppgifts-id för den nyskapade Omtexturering-uppgiften.

Fellägen

Name
400 - Bad Request
Description
Begäran var oacceptabel. Vanliga orsaker:
- Saknad parameter: Antingen model_url eller input_task_id måste anges.
- Saknad stil: Antingen text_style_prompt eller image_style_url måste anges.
- Ogiltig indatauppgift: input_task_id måste hänvisa till en lyckad uppgift från en modell som stöds.
- Ogiltigt modellformat: model_url pekar på en fil med en filändelse som inte stöds.
- Onåbar URL: model_url eller image_style_url kunde inte laddas ned.
Name
401 - Unauthorized
Description
Autentisering misslyckades. Kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckligt med credits för att utföra denna uppgift.
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.

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

Hämta en Omtexturering-uppgift

Denna endpoint låter dig hämta en Omtexturering-uppgift givet ett giltigt uppgifts-id. Se Objektet för Omtexturering-uppgift för att se vilka egenskaper som ingår i Omtexturering-uppgiftsobjektet.

Parametrar

Name
id
Type
path
Description
Unik identifierare för Omtexturering-uppgiften som ska hämtas.

Returnerar

Svaret innehåller Omtexturering-uppgiftsobjektet. Se avsnittet Objektet för Omtexturering-uppgift för detaljer.

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

Ta bort en Omtexturering-uppgift

Denna endpoint tar permanent bort en omtextureringsuppgift, inklusive alla associerade modeller och data. Denna åtgärd kan inte ångras.

Sökvägsparametrar

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

Returnerar

Returnerar 200 OK vid lyckat resultat.

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

Lista Omtexturering-uppgifter

Denna endpoint låter dig hämta en lista över Omtexturering-uppgifter.

Parametrar

Name
page_num
Type
integer
standard 1
Description
Sidnummer för paginering.
Name
page_size
Type
integer
standard 10
Description
Sidstorleksgräns. Högsta tillåtna är 50 objekt.
Name
sort_by
Type
string
Description
Fält att sortera efter.
Tillgängliga värden:
- +created_at: Sortera efter skapandetid i stigande ordning.
- -created_at: Sortera efter skapandetid i fallande ordning.

Returnerar

Returnerar en paginerad lista över Omtexturering-uppgiftsobjekten.

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

Strömma en Omtexturering-uppgift

Denna endpoint strömmar realtidsuppdateringar för en Omtexturering-uppgift med Server-Sent Events (SSE).

Parametrar

Name
id
Type
path
Description
Unik identifierare för Omtexturering-uppgiften som ska strömmas.

Returnerar

Returnerar en ström av Omtexturering-uppgiftsobjekten som Server-Sent Events.

För PENDING- eller IN_PROGRESS-uppgifter kommer svarsströmmen endast att innehålla nödvändiga fält för progress och 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
}

Omtextureringsuppgiftsobjektet

Omtextureringsuppgiftsobjektet är en arbetsenhet som Meshy använder för att generera en 3D-textur från antingen text- eller bildinmatningar. Modellen har följande egenskaper:

Egenskaper

Name
id
Type
string
Description
Unik identifierare för uppgiften. Även om vi använder ett k-sorterbart UUID för uppgifts-id:n som implementeringsdetalj bör du inte göra några antaganden om id:ts format.
Name
type
Type
string
Description
Typ av Omtextureringsuppgiften. Värdet är retexture.
Name
model_urls
Type
object
Description
Nedladdningsbar URL till den texturerade 3D-modellfilen som genereras av Meshy.
- Name
  glb
  Type
  string
  Description
  Nedladdningsbar URL till GLB-filen.
- Name
  fbx
  Type
  string
  Description
  Nedladdningsbar URL till FBX-filen.
- Name
  obj
  Type
  string
  Description
  Nedladdningsbar URL till OBJ-filen.
- Name
  usdz
  Type
  string
  Description
  Nedladdningsbar URL till USDZ-filen.
- Name
  mtl
  Type
  string
  Description
  Nedladdningsbar URL till MTL-filen, returneras tillsammans med OBJ-exporter när texturer finns.
- Name
  stl
  Type
  string
  Description
  Nedladdningsbar URL till STL-filen.
- Name
  3mf
  Type
  string
  Description
  Nedladdningsbar URL till 3MF-filen. Finns endast när 3mf begärdes via target_formats.
Name
text_style_prompt
Type
string
Description
Detta är den text-prompt som användes för att skapa textureringsuppgiften.
Name
image_style_url
Type
string
Description
Detta är bildinmatningen som användes för att skapa textureringsuppgiften.
Name
thumbnail_url
Type
string
Description
Nedladdningsbar URL till miniatyrbilden av modellfilen.
Name
alpha_thumbnail_url
Type
string
Description
Nedladdningsbar URL till en version med transparent bakgrund (RGBA) av thumbnail_url. Finns endast när uppgiften skapades med alpha_thumbnail: true och den transparenta förhandsvisningen renderades korrekt; annars utelämnas detta fält.
Name
progress
Type
integer
Description
Uppgiftens progress. Om uppgiften inte har startats ännu kommer den här egenskapen att vara 0. När uppgiften har slutförts kommer den att bli 100.
Name
started_at
Type
timestamp
Description
Tidsstämpel för när uppgiften startades, i millisekunder. Om uppgiften inte har startats ännu kommer den här egenskapen att vara 0.
En tidsstämpel representerar antalet millisekunder som har förflutit sedan 1 januari 1970 UTC, enligt standarden RFC 3339. Till exempel representeras fredag 1 september 2023 12:00:00 GMT som 1693569600000. Detta gäller för alla tidsstämplar i Meshy API.
Name
created_at
Type
timestamp
Description
Tidsstämpel för när uppgiften skapades, i millisekunder.
Name
expires_at
Type
timestamp
Description
Tidsstämpel för när uppgiftens resultat upphör att gälla, i millisekunder.
Name
finished_at
Type
timestamp
Description
Tidsstämpel för när uppgiften slutfördes, i millisekunder. Om uppgiften inte är slutförd ännu kommer den här egenskapen att vara 0.
Name
status
Type
string
Description
Uppgiftens status. Möjliga värden är ett av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
En array med textur-URL-objekt som genereras från uppgiften. Normalt innehåller detta endast ett textur-URL-objekt. Varje textur-URL har följande egenskaper:
- Name
  base_color
  Type
  string
  Description
  Nedladdningsbar URL till basfärgskartbilden.
- Name
  metallic
  Type
  string
  Description
  Nedladdningsbar URL till metallkartbilden.
  Om uppgiften skapas med enable_pbr: false kommer den här egenskapen att utelämnas.
- Name
  normal
  Type
  string
  Description
  Nedladdningsbar URL till normalmap-bilden.
  Om uppgiften skapas med enable_pbr: false kommer den här egenskapen att utelämnas.
- Name
  roughness
  Type
  string
  Description
  Nedladdningsbar URL till grovhetskartbilden.
  Om uppgiften skapas med enable_pbr: false kommer den här egenskapen att utelämnas.
- Name
  emission
  Type
  string
  Description
  Nedladdningsbar URL till emissionskartbilden.
  Om uppgiften skapas med enable_pbr: false, eller ai_model är meshy-5, kommer den här egenskapen att utelämnas.
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter.
Den här egenskapen visas endast när uppgiftens status är PENDING.
Name
task_error
Type
object
Description
Felinformation för misslyckade uppgifter. Se Fel för fullständig objektreferens för task_error.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av den här uppgiften. Finns när uppgiftens status är PENDING, IN_PROGRESS eller SUCCEEDED. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid fel).

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
}