Hertextureren-API

Hertextureren-API is een functie waarmee je Meshy's AI-mogelijkheden voor hertextureren in je eigen applicatie kunt integreren. In deze sectie vind je alle informatie die je nodig hebt om met deze API aan de slag te gaan.


POST/openapi/v1/retexture

Een Hertextureren-taak maken

Met dit endpoint kun je een nieuwe Hertextureren-taak maken. Raadpleeg Het Hertextureren-taakobject om te zien welke eigenschappen zijn opgenomen in het Hertextureren-taakobject.

Parameters

  • Name
    input_task_id
    Type
    string
    Verplicht
    Description

    De ID van de voltooide Afbeelding naar 3D- of Tekst naar 3D-taak die je wilt hertextureren. Deze taak moet een van de volgende taken zijn: Tekst naar 3D Preview, Tekst naar 3D Refine, Afbeelding naar 3D of Remesh. Daarnaast moet deze de status SUCCEEDED hebben.

  • Name
    model_url
    Type
    string
    Verplicht
    Description

    Geef een 3D-model op dat Meshy van textuur moet voorzien. Ondersteunde formaten: .glb, .gltf, .obj, .fbx, .stl.

    Er zijn twee manieren om het model op te geven:

    • Openbaar toegankelijke URL: Een URL die toegankelijk is vanaf het openbare internet.
    • Data URI: Een base64-gecodeerde Data URI van het model. Gebruik MIME type application/octet-stream. Voorbeeld: data:application/octet-stream;base64,<your base64-encoded model data>.
  • Name
    text_style_prompt
    Type
    string
    Verplicht
    Description

    Beschrijf de gewenste textuurstijl van het object met tekst. Maximaal 600 tekens.

  • Name
    image_style_url
    Type
    string
    Verplicht
    Description

    Geef een 2D-afbeelding op om het textureringsproces te sturen. We ondersteunen momenteel de formaten .jpg, .jpeg en .png.

    Er zijn twee manieren om de afbeelding op te geven:

    • Openbaar toegankelijke URL: Een URL die toegankelijk is vanaf het openbare internet
    • Data URI: Een base64-gecodeerde Data URI van de afbeelding. Voorbeeld van een Data URI: data:image/jpeg;base64,<your base64-encoded image data>
  • Name
    ai_model
    Type
    string
    standaard latest
    Description

    ID van het AI-model dat moet worden gebruikt voor hertextureren. Beschikbare waarden: meshy-5, meshy-6, latest (Meshy 6).

  • Name
    enable_original_uv
    Type
    boolean
    standaard false
    Description

    Behoud de bestaande UV-layout van het model in plaats van een nieuwe te genereren.

    • Als je een model hertextureert dat Meshy heeft gegenereerd (via input_task_id, of een model_url die naar een Meshy-output verwijst), stel dit dan in op true om de geoptimaliseerde UV-layout opnieuw te gebruiken.
    • Als je een geüpload model van derden hertextureert, stel dit dan in op true wanneer het al goede UV's heeft die je wilt behouden, of laat het op false staan om Meshy nieuwe UV's te laten uitpakken (het beste voor modellen zonder correcte UV-mapping).
  • Name
    enable_pbr
    Type
    boolean
    standaard false
    Description

    Genereer PBR-maps (metallic, roughness, normal) naast de basiskleur. Een emission map wordt ook opgenomen wanneer ai_model meshy-6 of latest is.

  • Name
    hd_texture
    Type
    boolean
    standaard false
    Description

    Genereer de basiskleurtextuur met een 4K-resolutie (4096×4096) voor meer detail.

  • Name
    remove_lighting
    Type
    boolean
    standaard true
    Description

    Verwijdert highlights en schaduwen uit de basiskleurtextuur, wat een schoner resultaat oplevert dat beter werkt onder aangepaste belichtingsopstellingen.

  • Name
    target_formats
    Type
    string[]
    Description

    Geeft aan welke 3D-bestandsformaten in de output moeten worden opgenomen. Alleen de aangevraagde formaten worden gegenereerd en geretourneerd, wat de voltooiingstijd van de taak kan verkorten. Wanneer dit wordt weggelaten, worden alle ondersteunde formaten opgenomen.

    Beschikbare waarden: glb, obj, fbx, stl, usdz, 3mf

  • Name
    alpha_thumbnail
    Type
    boolean
    standaard false
    Description

    Wanneer ingesteld op true, rendert de taak daarnaast een versie van de preview met transparante achtergrond (RGBA) en retourneert deze als alpha_thumbnail_url in de GET-respons. Het bestaande veld thumbnail_url blijft ongewijzigd.

Retourneert

De eigenschap result van de respons bevat de taak-id van de nieuw gemaakte Hertextureren-taak.

Foutmodi

  • Name
    400 - Bad Request
    Description

    De aanvraag was onacceptabel. Veelvoorkomende oorzaken:

    • Ontbrekende parameter: Ofwel model_url ofwel input_task_id moet worden opgegeven.
    • Ontbrekende stijl: Ofwel text_style_prompt ofwel image_style_url moet worden opgegeven.
    • Ongeldige invoertaak: De input_task_id moet verwijzen naar een geslaagde taak van een ondersteund model.
    • Ongeldig modelformaat: De model_url verwijst naar een bestand met een niet-ondersteunde extensie.
    • Onbereikbare URL: De model_url of image_style_url kon niet worden gedownload.
  • Name
    401 - Unauthorized
    Description

    De authenticatie is mislukt. Controleer je API-sleutel.

  • Name
    402 - Payment Required
    Description

    Onvoldoende credits om deze taak uit te voeren.

  • Name
    429 - Too Many Requests
    Description

    Je hebt je rate limit overschreden.

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

Een Hertextureren-taak ophalen

Met deze endpoint kun je een Hertextureren-taak ophalen met een geldige taak-id. Raadpleeg Het Hertextureren-taakobject om te zien welke eigenschappen zijn opgenomen in het Hertextureren-taakobject.

Parameters

  • Name
    id
    Type
    path
    Description

    Unieke identifier voor de Hertextureren-taak die moet worden opgehaald.

Retourneert

De respons bevat het Hertextureren-taakobject. Bekijk de sectie Het Hertextureren-taakobject voor details.

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

Een Hertextureren-taak verwijderen

Deze endpoint verwijdert permanent een hertextureren-taak, inclusief alle bijbehorende modellen en gegevens. Deze actie is onomkeerbaar.

Padparameters

  • Name
    id
    Type
    path
    Description

    De ID van de hertextureren-taak die moet worden verwijderd.

Retourneert

Retourneert 200 OK bij succes.

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

Hertextureren-taken weergeven

Met deze endpoint kun je een lijst met Hertextureren-taken ophalen.

Parameters

  • Name
    page_num
    Type
    integer
    standaard 1
    Description

    Paginanummer voor paginering.

  • Name
    page_size
    Type
    integer
    standaard 10
    Description

    Limiet voor paginagrootte. Het maximaal toegestane aantal is 50 items.

  • Name
    sort_by
    Type
    string
    Description

    Veld om op te sorteren.

    Beschikbare waarden:

    • +created_at: Sorteer op aanmaaktijd in oplopende volgorde.
    • -created_at: Sorteer op aanmaaktijd in aflopende volgorde.

Retourneert

Retourneert een gepagineerde lijst met De Hertextureren-taakobjecten.

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

Een Hertextureren-taak streamen

Deze endpoint streamt realtime updates voor een Hertextureren-taak met Server-Sent Events (SSE).

Parameters

  • Name
    id
    Type
    path
    Description

    Unieke identificatie voor de Hertextureren-taak die moet worden gestreamd.

Retourneert

Retourneert een stream van De Hertextureren-taakobjecten als Server-Sent Events.

Voor PENDING- of IN_PROGRESS-taken bevat de responsstream alleen de noodzakelijke velden progress en 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
}

Het Hertextureren-taakobject

Het Hertextureren-taakobject is een werkeenheid die Meshy gebruikt om een 3D-textuur te genereren op basis van tekst- of afbeeldingsinvoer. Het model heeft de volgende eigenschappen:

Eigenschappen

  • Name
    id
    Type
    string
    Description

    Unieke identifier voor de taak. Hoewel we een k-sorteerbare UUID gebruiken voor taak-id's als implementatiedetail, moet je geen aannames doen over de indeling van de id.

  • Name
    type
    Type
    string
    Description

    Type van de Hertextureren-taak. De waarde is retexture.

  • Name
    model_urls
    Type
    object
    Description

    Downloadbare URL naar het getextureerde 3D-modelbestand dat door Meshy is gegenereerd.

    • Name
      glb
      Type
      string
      Description

      Downloadbare URL naar het GLB-bestand.

    • Name
      fbx
      Type
      string
      Description

      Downloadbare URL naar het FBX-bestand.

    • Name
      obj
      Type
      string
      Description

      Downloadbare URL naar het OBJ-bestand.

    • Name
      usdz
      Type
      string
      Description

      Downloadbare URL naar het USDZ-bestand.

    • Name
      mtl
      Type
      string
      Description

      Downloadbare URL naar het MTL-bestand, geretourneerd naast OBJ-exports wanneer texturen aanwezig zijn.

    • Name
      stl
      Type
      string
      Description

      Downloadbare URL naar het STL-bestand.

    • Name
      3mf
      Type
      string
      Description

      Downloadbare URL naar het 3MF-bestand. Alleen aanwezig wanneer 3mf is aangevraagd via target_formats.

  • Name
    text_style_prompt
    Type
    string
    Description

    Dit is de tekstprompt die is gebruikt om de textureringstaak te maken.

  • Name
    image_style_url
    Type
    string
    Description

    Dit is de afbeeldingsinvoer die is gebruikt om de textureringstaak te maken.

  • Name
    thumbnail_url
    Type
    string
    Description

    Downloadbare URL naar de thumbnail-afbeelding van het modelbestand.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    Downloadbare URL naar een versie met transparante achtergrond (RGBA) van thumbnail_url. Alleen aanwezig wanneer de taak is gemaakt met alpha_thumbnail: true en de transparante preview succesvol is gerenderd; anders wordt dit veld weggelaten.

  • Name
    progress
    Type
    integer
    Description

    Progress van de taak. Als de taak nog niet is gestart, is deze eigenschap 0. Zodra de taak is geslaagd, wordt dit 100.

  • Name
    started_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer de taak is gestart, in milliseconden. Als de taak nog niet is gestart, is deze eigenschap 0.

  • Name
    created_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer de taak is gemaakt, in milliseconden.

  • Name
    expires_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer het taakresultaat verloopt, in milliseconden.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer de taak is voltooid, in milliseconden. Als de taak nog niet is voltooid, is deze eigenschap 0.

  • Name
    status
    Type
    string
    Description

    Status van de taak. Mogelijke waarden zijn een van PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    texture_urls
    Type
    array
    Description

    Een array met textuur-URL-objecten die vanuit de taak worden gegenereerd. Normaal bevat deze slechts één textuur-URL-object. Elke textuur-URL heeft de volgende eigenschappen:

    • Name
      base_color
      Type
      string
      Description

      Downloadbare URL naar de base color map-afbeelding.

    • Name
      metallic
      Type
      string
      Description

      Downloadbare URL naar de metallic map-afbeelding.

    • Name
      normal
      Type
      string
      Description

      Downloadbare URL naar de normal map-afbeelding.

    • Name
      roughness
      Type
      string
      Description

      Downloadbare URL naar de roughness map-afbeelding.

    • Name
      emission
      Type
      string
      Description

      Downloadbare URL naar de emission map-afbeelding.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Het aantal voorgaande taken.

  • Name
    task_error
    Type
    object
    Description

    Foutdetails voor mislukte taken. Zie Fouten voor de volledige task_error-objectreferentie.

  • Name
    consumed_credits
    Type
    integer
    Description

    Het aantal credits dat door deze taak is verbruikt. Aanwezig wanneer de taakstatus PENDING, IN_PROGRESS of SUCCEEDED is. Retourneert 0 voor FAILED-taken (credits worden bij mislukking terugbetaald).

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
}