Afbeelding naar 3D API

Afbeelding naar 3D API is een functie waarmee je Meshy's mogelijkheden voor Afbeelding naar 3D kunt integreren in je eigen applicatie. In dit gedeelte vind je alle informatie die je nodig hebt om aan de slag te gaan met deze API.

POST/openapi/v1/image-to-3d

Een Afbeelding naar 3D-taak maken

Met deze endpoint kun je een nieuwe Afbeelding naar 3D-taak maken. Raadpleeg Het Afbeelding naar 3D-taakobject om te zien welke eigenschappen deel uitmaken van het Afbeelding naar 3D-taakobject.

De taak wordt op de achtergrond uitgevoerd. Voor hoe lang dit meestal duurt, zie Verwerkingstijden.

Parameters

Slechts één van input_task_id of image_url is vereist. Als beide worden opgegeven, heeft input_task_id prioriteit.

Name
input_task_id
Type
string
Verplicht
Description
De ID van een voltooide afbeeldingsgeneratietaak waarvan de uitvoer als invoerafbeelding moet worden gebruikt. Deze taak moet een van de volgende taken zijn: Tekst naar afbeelding of Afbeelding naar afbeelding. Daarnaast moet deze via de API zijn uitgevoerd, de status SUCCEEDED hebben en precies één afbeelding opleveren.

Name
image_url
Type
string
Verplicht
Description
Geef een afbeelding op die Meshy kan gebruiken bij het maken van het model. We ondersteunen momenteel de formaten .jpg, .jpeg, .png en .webp.
Maximale bestandsgrootte: 20 MB.
Er zijn twee manieren om de afbeelding op te geven:
- Publiek 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
model_type
Type
string
standaard standard
Description
Geef het type 3D-mesh-generatie op.
Beschikbare waarden:
- standard: Normale 3D-mesh-generatie met hoog detailniveau.
- smart-topology: Kies een Smart Topology-model met ai_model (meshy-t2 of meshy-t2.5).
- lowpoly (verouderd, wordt uitgefaseerd op 30 oktober 2026): Genereert low-poly mesh geoptimaliseerd voor schonere polygonen. We raden in plaats daarvan Meshy T2.5 aan: smart-topology met meshy-t2.5.
Wanneer smart-topology is geselecteerd, worden should_remesh, save_pre_remeshed_model en decimation_mode genegeerd, en wordt alleen topology: triangle geaccepteerd.
lowpoly wordt uitgefaseerd op 30 oktober 2026. Na die datum geven verzoeken met model_type: "lowpoly" een foutmelding. We raden aan over te schakelen naar Meshy T2.5 (model_type: "smart-topology" met ai_model: "meshy-t2.5"). Wanneer lowpoly is geselecteerd, worden ai_model, topology, target_polycount, should_remesh en save_pre_remeshed_model genegeerd.
Name
ai_model
Type
string
standaard latest
Description
ID van het te gebruiken model. De beschikbare waarden zijn afhankelijk van model_type.
Standaardgeneratie (model_type: standard):
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (verouderd): gebruik in plaats daarvan meshy-7.1.
Smart Topology-generatie (model_type: smart-topology):
- meshy-t2: het Smart Topology-model — schonere topology, van nature gescheiden onderdelen, driehoeksuitvoer en een aantal vlakken dat je kunt instellen met target_polycount.
- meshy-t2.5 (standaard): Scherper detail voor game-assets. Driehoeksuitvoer en een aantal vlakken dat je kunt instellen met target_polycount.
Name
geometry_resolution
Type
string
standaard standard
Description
Pass voor geometriegeneratie. 2k voert de Ultra-pass uit op 2048³; 4k voert deze uit op 4096³ voor het fijnste oppervlaktedetail.
Beschikbare waarden: standard, 2k, 4k
Vereist meshy-7.1 of latest.
Name
ultra_mode
Type
boolean
⚠ verouderd
standaard false
Description
Gebruik in plaats daarvan geometry_resolution. ultra_mode: true is gelijk aan geometry_resolution: "2k".
Name
should_texture
Type
boolean
standaard true
Description
Bepaalt of texturen worden gegenereerd. Als dit wordt ingesteld op false, wordt de texturerfase overgeslagen en wordt een mesh zonder texturen geleverd.

Alleen van toepassing wanneer should_texture = true

Name
enable_pbr
Type
boolean
standaard false
Description
Genereer PBR-maps (metallic, roughness, normal) naast de basiskleur. Er wordt ook een emissiekaart meegeleverd wanneer ai_model meshy-6 is, behalve bij texture_resolution: 8k. meshy-6-lite, meshy-7.1, meshy-t2 en latest produceren geen emissiekaart.
Name
texture_resolution
Type
string
standaard 2k
Description
Resolutie van de basiskleurtextuur. Een van 2k (2048×2048), 4k (4096×4096) of 8k (8192×8192). Hogere resoluties leggen meer oppervlaktedetail vast.
4k en 8k zijn niet beschikbaar bij ai_model meshy-6-lite. Bij 8k wordt geen emissiekaart geproduceerd.
Name
hd_texture
Type
boolean
⚠ verouderd
standaard false
Description
Gebruik in plaats daarvan texture_resolution — gelijk aan texture_resolution: "4k". Wanneer beide zijn ingesteld, heeft texture_resolution voorrang.
Name
texture_prompt
Type
string
Description
Geef een tekstprompt op om het textureproces te sturen. Maximaal 800 tekens.
Name
texture_image_url
Type
string
Description
Geef een 2D-afbeelding op om het textureproces te sturen. We ondersteunen momenteel de formaten .jpg, .jpeg, .png en .webp.
Maximale bestandsgrootte: 20 MB.
Er zijn twee manieren om de afbeelding op te geven:
- Publiek 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>
Het textureren met een afbeelding werkt mogelijk niet optimaal als er aanzienlijke geometrische verschillen zijn tussen het originele asset en de geüploade afbeelding. Slechts één van texture_image_url of texture_prompt mag worden gebruikt om het textureproces te sturen. Als beide parameters worden opgegeven, wordt standaard texture_prompt gebruikt om het model te textureren. Textureren via tekst of afbeelding kost 10 credits per taak.

Name
should_remesh
Type
boolean
standaard false (Meshy 6 and Meshy 7 models), true (others)
Description
Bepaalt of de remeshfase wordt ingeschakeld. Voor het model met de hoogste kwaliteit raden we aan should_remesh op false te zetten.

Alleen van toepassing wanneer should_remesh = true

Name
topology
Type
string
standaard triangle
Description
Geef de topology van het gegenereerde model op.
Beschikbare waarden:
- quad: Genereer een overwegend uit vierhoeken bestaande mesh.
- triangle: Genereer een gereduceerde driehoeksmesh.
Smart Topology-uitvoer bestaat alleen uit driehoeken. Het combineren van quad met ai_model meshy-t2 of meshy-t2.5 geeft een foutmelding.
Name
decimation_mode
Type
integer
Description
Schakel adaptieve reductie in door een polygonaantalniveau in te stellen. Wanneer dit is ingesteld, wordt target_polycount genegeerd.
Beschikbare waarden:
- 1: Adaptief — ultrahoog polygonaantal.
- 2: Adaptief — hoog polygonaantal.
- 3: Adaptief — gemiddeld polygonaantal.
- 4: Adaptief — laag polygonaantal.
Name
save_pre_remeshed_model
Type
boolean
standaard false
Description
Wanneer ingesteld op true, slaat Meshy ook een extra GLB-bestand op voordat de remeshfase is voltooid.

Name
target_polycount
Type
integer
Description
Beoogd aantal polygonen (vlakken) in de uitvoer. Het werkelijke aantal kan afwijken van het doel, afhankelijk van de geometrie.
target_polycount is in twee onafhankelijke gevallen van toepassing:
- Remesh — met should_remesh: true op een standard-model. De mesh wordt geremeshed (gereduceerd) tot ongeveer dit aantal. Bereik 100 tot 300.000, standaard 30.000. Als decimation_mode is ingesteld, heeft dit voorrang en wordt target_polycount genegeerd.
- Smart Topology — met model_type: smart-topology en ai_model meshy-t2 of meshy-t2.5. Het model wordt direct met dit aantal vlakken gegenereerd; er wordt geen remesh uitgevoerd en should_remesh is niet vereist. Voor meshy-t2: bereik 100 tot 15.000, standaard 4.000. Voor meshy-t2.5: bereik 100 tot 30.000, standaard 15.000.

Name
symmetry_mode
Type
string
⚠ verouderd
standaard auto
Description
Verouderd. Deze parameter heeft geen invloed meer op de uitvoer.
Het veld symmetry_mode bepaalt het symmetriegedrag tijdens het modelgeneratieproces.
De geldige waarden zijn:
- off: Schakelt symmetrie uit.
- auto: Bepaalt en past automatisch symmetrie toe op basis van de invoergeometrie.
- on: Dwingt symmetrie af tijdens de generatie.
Name
pose_mode
Type
string
standaard ""
Description
Geef de posemode voor het gegenereerde model op.
Beschikbare waarden:
- a-pose: Genereer het model in een A-pose.
- t-pose: Genereer het model in een T-pose.
- "" (lege tekenreeks): Geen specifieke pose toegepast.
Name
is_a_t_pose
Type
boolean
⚠ verouderd
standaard false
Description
Gebruik in plaats daarvan pose_mode. Of het model in een A/T-pose moet worden gegenereerd.
Name
surface_mode
Type
string
⚠ verouderd
Description
Heeft geen invloed meer op de uitvoer. Het selecteerde een modelgeneratie die inmiddels is uitgefaseerd; gebruik in plaats daarvan ai_model.
Geaccepteerde waarden zijn organic en hard; elke andere waarde geeft 400 terug.
Name
image_enhancement
Type
boolean
standaard true
Description
Optimaliseert de invoerafbeelding voor betere resultaten. Zet op false om het exacte uiterlijk van de invoerafbeelding te behouden zonder enige stijlbewerking.
Wordt alleen ondersteund wanneer ai_model meshy-6, meshy-7.1 of latest is. Het instellen hiervan met meshy-6-lite of met model_type: smart-topology geeft een foutmelding.
Name
remove_lighting
Type
boolean
standaard true
Description
Verwijdert hooglichten en schaduwen uit de basiskleurtextuur, wat een schoner resultaat oplevert dat beter werkt bij aangepaste belichtingsopstellingen.
Heeft alleen effect wanneer ai_model meshy-6 is. meshy-7.1 en latest accepteren de parameter en negeren deze. Het instellen hiervan met meshy-6-lite of met model_type: smart-topology geeft een foutmelding.
Name
moderation
Type
boolean
standaard false
Description
Wanneer ingesteld op true, wordt de invoerinhoud automatisch gecontroleerd op mogelijk schadelijke inhoud. Als schadelijke inhoud wordt gedetecteerd, gaat de taak niet verder met de generatie.
De inhoud van de invoer image_url, texture_image_url en texture_prompt wordt gecontroleerd.
Name
target_formats
Type
string[]
Description
Geeft aan welke 3D-bestandsformaten in de uitvoer moeten worden opgenomen. Alleen de gevraagde formaten worden gegenereerd en geretourneerd, wat de voltooiingstijd van de taak kan verkorten. Indien weggelaten, worden alle ondersteunde formaten meegenomen.
Beschikbare waarden: glb, obj, fbx, stl, usdz, 3mf
Indien weggelaten, worden alle formaten behalve 3mf gegenereerd. 3mf wordt alleen meegenomen wanneer dit expliciet is opgegeven.
Name
auto_size
Type
boolean
standaard false
Description
Wanneer ingesteld op true, gebruikt de service AI-visie om automatisch de werkelijke hoogte van het object te schatten en het model dienovereenkomstig in grootte aan te passen. De oorsprong wordt standaard bottom, tenzij origin_at expliciet is ingesteld.
Name
alpha_thumbnail
Type
boolean
standaard false
Description
Wanneer ingesteld op true, rendert de taak bovendien 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.
Name
multi_view_thumbnails
Type
boolean
standaard false
Description
Wanneer ingesteld op true, rendert de taak bovendien vier kardinale weergaven als miniaturen (voor, rechts, achter, links) en retourneert deze onder thumbnail_urls in de GET-respons. Het bestaande veld thumbnail_url blijft ongewijzigd en verwijst nog steeds naar de vooraanzicht, zodat bestaande clients niet worden beïnvloed.
Voegt ongeveer 3 seconden toe aan de latentie van de taak.

Alleen van toepassing wanneer auto_size = true

Name
origin_at
Type
string
standaard bottom
Description
Positie van de oorsprong wanneer auto_size is ingeschakeld.
Beschikbare waarden: bottom, center.

Resultaten

De eigenschap result van de respons bevat de taak-id van de nieuw gemaakte Afbeelding naar 3D-taak.

Foutmodi

Name
400 - Bad Request
Description
Het verzoek was onacceptabel. Veelvoorkomende oorzaken:
- Ontbrekende parameter: Ofwel image_url ofwel input_task_id moet worden opgegeven.
- Ongeldige invoertaak: input_task_id moet verwijzen naar een SUCCEEDED Tekst naar afbeelding- of Afbeelding naar afbeelding-taak die precies één afbeelding oplevert.
- Ongeldig afbeeldingsformaat: De opgegeven image_url heeft geen ondersteund formaat (.jpg, .jpeg, .png, .webp).
- Onbereikbare URL: De image_url kon niet worden gedownload (404 of timeout).
- Afbeelding te groot: De afbeelding van image_url of texture_image_url is groter dan 20 MB.
- Ongeldige Data URI: De base64-tekenreeks is onjuist opgemaakt.
- Ongeldige parametercombinatie: enable_pbr wordt alleen ondersteund wanneer should_texture true is.
- Niet-ondersteund model voor low poly: ai_model: "meshy-6-lite" ondersteunt model_type: "lowpoly" niet.
- Niet-ondersteund model voor Ultra: geometry_resolution vereist meshy-7.1 of latest.
- Niet-ondersteund model voor afbeeldingsopties: image_enhancement of remove_lighting is ingesteld met ai_model: "meshy-6-lite" of model_type: "smart-topology".
Name
401 - Unauthorized
Description
Authenticatie 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/image-to-3d

# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -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>"
  }'

# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -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>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

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

GET/openapi/v1/image-to-3d/:id

Een Afbeelding naar 3D-taak ophalen

Deze endpoint stelt u in staat om een Afbeelding naar 3D-taak op te halen op basis van een geldig taak-id. Raadpleeg Het Afbeelding naar 3D-taakobject om te zien welke eigenschappen deel uitmaken van het Afbeelding naar 3D-taakobject.

Parameters

Name
id
Type
path
Description
Unieke identifier voor de Afbeelding naar 3D-taak die moet worden opgehaald.

Resultaten

Het antwoord bevat het Afbeelding naar 3D-taakobject. Bekijk de sectie Het Afbeelding naar 3D-taakobject voor details.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "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": 30
}

DELETE/openapi/v1/image-to-3d/:id

Een Image to 3D-taak verwijderen

Deze endpoint verwijdert permanent een Afbeelding naar 3D-taak, inclusief alle bijbehorende modellen en gegevens. Deze actie is onomkeerbaar.

Pad parameters

Name
id
Type
path
Description
De ID van de Afbeelding naar 3D-taak die moet worden verwijderd.

Taakstatus

Een taak die nog PENDING is, wordt verwijderd en de credits die op het moment van aanmaken zijn verbruikt, worden terugbetaald.

Een taak die al IN_PROGRESS is, kan niet worden verwijderd: het verzoek wordt afgewezen met 409 Conflict en de taak blijft doorlopen. Credits voor een taak die de worker al is gestart, zijn niet terugbetaalbaar, dus het verwijderen ervan tijdens het uitvoeren zou je zowel de credits als het resultaat kosten. Wacht tot de taak SUCCEEDED, FAILED of CANCELED bereikt, en verwijder deze dan.

Een taak in een eindstatus (SUCCEEDED, FAILED of CANCELED) wordt verwijderd zonder terugbetaling.

Resultaten

Geeft 200 OK terug bij succes, of 409 Conflict wanneer de taak IN_PROGRESS is.

Request

DELETE

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -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 is left 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."
}

GET/openapi/v1/image-to-3d

List Image to 3D Tasks

Met deze endpoint kun je een lijst met Afbeelding naar 3D-taken ophalen.

Parameters

Optionele attributen

Name
page_num
Type
integer
Description
Paginanummer voor paginering. Begint bij en standaard is 1.
Name
page_size
Type
integer
Description
Limiet voor paginagrootte. Standaard 10 items. Maximaal toegestaan is 100 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.

Returns

Retourneert een gepagineerde lijst van The Image to 3D Task Objects.

Request

GET

/openapi/v1/image-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "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=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "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": 30
  }
]

GET/openapi/v1/image-to-3d/:id/stream

Stream een Afbeelding naar 3D-taak

Deze endpoint streamt realtime updates voor een Afbeelding naar 3D-taak met behulp van Server-Sent Events (SSE).

Parameters

Name
id
Type
path
Description
Unieke identifier voor de Afbeelding naar 3D-taak die gestreamd moet worden.

Retourneert

Retourneert een stream van De Afbeelding naar 3D-taakobjecten als Server-Sent Events.

Voor taken met status PENDING of IN_PROGRESS bevat de response-stream alleen de noodzakelijke velden progress en status.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-to-3d/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",
  "type": "image-to-3d",
  "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=***",
  "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "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": 30
}

Het Image to 3D Task-object

Het Image to 3D Task-object is een werkeenheid die Meshy bijhoudt om een 3D-model te genereren op basis van een afbeelding-invoer. Het object heeft de volgende eigenschappen:

Eigenschappen

Name
id
Type
string
Description
Unieke identifier voor de taak. Hoewel we als implementatiedetail een k-sortable UUID gebruiken voor taak-id's, mag je geen aannames doen over het formaat van de id.
Name
type
Type
string
Description
Type van de Image to 3D-taak. De waarde is image-to-3d.
Name
model_urls
Type
object
Description
Downloadbare URL naar het getextureerde 3D-modelbestand dat door Meshy is gegenereerd. De eigenschap voor een formaat wordt weggelaten als het formaat niet is gegenereerd, in plaats van een lege string te retourneren.
- 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 samen met OBJ-exports wanneer er 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
  pre_remeshed_glb
  Type
  string
  Description
  Downloadbare URL naar de originele GLB-uitvoer vóór het remeshen.
  Alleen beschikbaar wanneer de taak is aangemaakt met zowel should_remesh: true als save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
Downloadbare URL naar de thumbnail-afbeelding van het modelbestand. Gelijkwaardig aan thumbnail_urls.front wanneer aanwezig, behouden voor achterwaartse compatibiliteit.
Name
alpha_thumbnail_url
Type
string
Description
Downloadbare URL naar een versie van thumbnail_url met transparante achtergrond (RGBA). Alleen aanwezig wanneer de taak is aangemaakt met alpha_thumbnail: true en de transparante preview succesvol is gerenderd; anders wordt dit veld weggelaten.
Name
thumbnail_urls
Type
object
Description
Downloadbare URL's voor vier thumbnails van het gegenereerde 3D-model vanuit de vier hoofdrichtingen. Elke waarde is een ondertekende URL naar een 512×512 PNG, gerenderd met dezelfde materialen en belichting als thumbnail_url. Handig om het model vanuit meerdere hoeken te bekijken in batchpipelines zonder de GLB te downloaden.
Alleen aanwezig wanneer de taak is aangemaakt met multi_view_thumbnails: true en de status SUCCEEDED heeft bereikt. Oudere taken en taken die zijn aangemaakt zonder deze opt-in bevatten dit veld niet.
- Name
  front
  Type
  string
  Description
  Vooraanzicht, 0° rotatie om de verticale as (komt overeen met thumbnail_url).
- Name
  right
  Type
  string
  Description
  Rechteraanzicht, 90° rotatie.
- Name
  back
  Type
  string
  Description
  Achteraanzicht, 180° rotatie.
- Name
  left
  Type
  string
  Description
  Linkeraanzicht, 270° rotatie.
Name
texture_prompt
Type
string
Description
De tekstprompt die is gebruikt om het textureringsproces te sturen.
Name
texture_image_url
Type
string
Description
Downloadbare URL naar de textuurafbeelding die is gebruikt om het textureringsproces te sturen.
Name
ultra_mode
Type
boolean
⚠ verouderd
Description
Verouderd; lees in plaats daarvan geometry_resolution.
Name
geometry_resolution
Type
string
Description
De Ultra-laag waarmee de taak is uitgevoerd (2k of 4k); weggelaten voor standard.
Name
progress
Type
integer
Description
Voortgang 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.
Een tijdstempel vertegenwoordigt het aantal milliseconden dat is verstreken sinds 1 januari 1970 UTC, volgens de RFC 3339-standaard. Bijvoorbeeld, vrijdag 1 september 2023 12:00:00 PM GMT wordt weergegeven als 1693569600000. Dit geldt voor alle tijdstempels in Meshy API.
Name
created_at
Type
timestamp
Description
Tijdstempel van wanneer de taak is aangemaakt, 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 PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Een array van textuur-URL-objecten die door de taak zijn gegenereerd. Normaal gesproken bevat dit slechts één textuur-URL-object. Elke textuur-URL heeft de volgende eigenschappen:
- Name
  base_color
  Type
  string
  Description
  Downloadbare URL naar de basiskleur-map-afbeelding.
- Name
  metallic
  Type
  string
  Description
  Downloadbare URL naar de metallic-map-afbeelding.
  Als de taak is aangemaakt met enable_pbr: false, wordt deze eigenschap weggelaten.
- Name
  normal
  Type
  string
  Description
  Downloadbare URL naar de normal map-afbeelding.
  Als de taak is aangemaakt met enable_pbr: false, wordt deze eigenschap weggelaten.
- Name
  roughness
  Type
  string
  Description
  Downloadbare URL naar de roughness-map-afbeelding.
  Als de taak is aangemaakt met enable_pbr: false, wordt deze eigenschap weggelaten.
- Name
  emission
  Type
  string
  Description
  Downloadbare URL naar de emission-map-afbeelding.
  Als de taak is aangemaakt met enable_pbr: false, of als ai_model gelijk is aan meshy-6-lite, meshy-7.1, meshy-t2, of latest, wordt deze eigenschap weggelaten.
Name
preceding_tasks
Type
integer
Description
Het aantal voorafgaande taken.
De waarde van dit veld is alleen betekenisvol als de taakstatus PENDING is.
Name
task_error
Type
object
Description
Foutgegevens voor mislukte taken. Zie Fouten voor de volledige referentie van het task_error-object.
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 terugbetaald bij mislukking).

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}