Bild till 3D API

Bild till 3D API är en funktion som låter dig integrera Meshys funktioner för Bild till 3D 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/image-to-3d

Skapa en Bild till 3D-uppgift

Denna endpoint gör det möjligt att skapa en ny Bild till 3D-uppgift. Se The Image to 3D Task Object för att se vilka egenskaper som ingår i objektet för en Bild till 3D-uppgift.

Uppgiften körs i bakgrunden. För information om hur lång tid det brukar ta, se Processing Times.

Parametrar

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

Name
input_task_id
Type
string
Obligatorisk
Description
ID för en slutförd bildgenereringsuppgift vars resultat ska användas som indatabild. Denna uppgift måste vara en av följande: Text till bild eller Bild till bild. Dessutom måste den ha körts via API:et, ha status SUCCEEDED och producera exakt en bild.

Name
image_url
Type
string
Obligatorisk
Description
Ange en bild för Meshy att använda vid modellskapande. Vi stöder för närvarande formaten .jpg, .jpeg, .png och .webp.
Maximal filstorlek: 20 MB.
Det finns två sätt att ange bilden:
- Offentligt tillgänglig URL: En URL som är tillgänglig från det öppna internet.
- Data URI: En base64-kodad data-URI av bilden. Exempel på en data-URI: data:image/jpeg;base64,<your base64-encoded image data>.

Name
model_type
Type
string
standard standard
Description
Ange typen av 3D-nätgenerering.
Tillgängliga värden:
- standard: Vanlig 3D-nätgenerering med hög detaljnivå.
- smart-topology: Välj en Smart Topology-modell med ai_model (meshy-t2 eller meshy-t2.5).
- lowpoly (föråldrad, avvecklas 30 oktober 2026): Genererar low-poly-nät optimerat för renare polygoner. Vi rekommenderar Meshy T2.5 istället: smart-topology med meshy-t2.5.
När smart-topology väljs ignoreras should_remesh, save_pre_remeshed_model och decimation_mode, och endast topology: triangle accepteras.
lowpoly kommer att avvecklas 30 oktober 2026. Efter det datumet kommer förfrågningar med model_type: "lowpoly" att returnera ett fel. Vi rekommenderar att byta till Meshy T2.5 (model_type: "smart-topology" med ai_model: "meshy-t2.5"). När lowpoly väljs ignoreras ai_model, topology, target_polycount, should_remesh och save_pre_remeshed_model.
Name
ai_model
Type
string
standard latest
Description
ID för modellen som ska användas. Tillgängliga värden beror på model_type.
Standardgenerering (model_type: standard):
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (föråldrad): använd meshy-7.1 istället.
Smart Topology-generering (model_type: smart-topology):
- meshy-t2: Smart Topology-modellen — renare topology, naturligt separerade delar, triangelutdata och ett antal ytor som kan anges med target_polycount.
- meshy-t2.5 (standard): Skarpare detaljer för spel-assets. Triangelutdata och ett antal ytor som kan anges med target_polycount.
Name
geometry_resolution
Type
string
standard standard
Description
Geometrigenereringssteg. 2k kör Ultra-steget vid 2048³; 4k kör det vid 4096³ för finaste ytdetalj.
Tillgängliga värden: standard, 2k, 4k
Kräver meshy-7.1 eller latest.
Name
ultra_mode
Type
boolean
⚠ föråldrad
standard false
Description
Använd geometry_resolution istället. ultra_mode: true motsvarar geometry_resolution: "2k".
Name
should_texture
Type
boolean
standard true
Description
Avgör om texturer genereras. Om värdet sätts till false hoppas texturfasen över, vilket ger ett nät utan texturer.

Gäller endast när should_texture = true

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, förutom vid texture_resolution: 8k. meshy-6-lite, meshy-7.1, meshy-t2 och latest genererar inte någon emissionskarta.
Name
texture_resolution
Type
string
standard 2k
Description
Upplösning för basfärgstextur. En av 2k (2048×2048), 4k (4096×4096) eller 8k (8192×8192). Högre upplösningar fångar mer ytdetalj.
4k och 8k är inte tillgängliga med ai_model meshy-6-lite. Vid 8k genereras ingen emissionskarta.
Name
hd_texture
Type
boolean
⚠ föråldrad
standard false
Description
Använd texture_resolution istället — motsvarar texture_resolution: "4k". Om båda anges har texture_resolution företräde.
Name
texture_prompt
Type
string
Description
Ange en textprompt för att styra texturprocessen. Max 800 tecken.
Name
texture_image_url
Type
string
Description
Ange en 2D-bild för att styra texturprocessen. Vi stöder för närvarande formaten .jpg, .jpeg, .png och .webp.
Maximal filstorlek: 20 MB.
Det finns två sätt att ange bilden:
- Offentligt tillgänglig URL: En URL som är tillgänglig från det öppna internet
- Data URI: En base64-kodad data-URI av bilden. Exempel på en data-URI: data:image/jpeg;base64,<your base64-encoded image data>
Bildtexturering kanske inte fungerar optimalt om det finns stora geometriska skillnader mellan den ursprungliga asseten och den uppladdade bilden. Endast en av texture_image_url eller texture_prompt kan användas för att styra texturprocessen. Om båda parametrarna anges kommer texture_prompt som standard att användas för att textura modellen. Texturering via antingen text eller bild kostar 10 credits per uppgift.

Name
should_remesh
Type
boolean
standard false (Meshy 6 and Meshy 7 models), true (others)
Description
Styr om remesh-fasen ska aktiveras. För modellen med högst kvalitet rekommenderar vi att sätta should_remesh till false.

Gäller endast när should_remesh = true

Name
topology
Type
string
standard triangle
Description
Ange topology för den genererade modellen.
Tillgängliga värden:
- quad: Generera ett nät som domineras av fyrhörningar (quad).
- triangle: Generera ett decimerat triangelnät.
Smart Topology-utdata är endast i triangelform. Att begära quad tillsammans med ai_model meshy-t2 eller meshy-t2.5 returnerar ett fel.
Name
decimation_mode
Type
integer
Description
Aktivera adaptiv decimering genom att ange en polygonantalsnivå. När denna är satt ignoreras target_polycount.
Tillgängliga värden:
- 1: Adaptiv — ultrahögt polygonantal.
- 2: Adaptiv — högt polygonantal.
- 3: Adaptiv — medelhögt polygonantal.
- 4: Adaptiv — lågt polygonantal.
Name
save_pre_remeshed_model
Type
boolean
standard false
Description
När värdet sätts till true lagrar Meshy även en extra GLB-fil innan remesh-fasen slutförts.

Name
target_polycount
Type
integer
Description
Målvärde för antal polygoner (ytor) i resultatet. Det faktiska antalet kan avvika från målvärdet beroende på geometrin.
target_polycount har effekt i två oberoende fall:
- Remesh — med should_remesh: true på en standard-modell. Nätet remeshas (decimeras) till ungefär detta antal. Intervall 100 till 300 000, standard 30 000. Om decimation_mode är satt har den prioritet och target_polycount ignoreras.
- Smart Topology — med model_type: smart-topology och ai_model meshy-t2 eller meshy-t2.5. Modellen genereras direkt med detta antal ytor; ingen remesh körs och should_remesh krävs inte. För meshy-t2: intervall 100 till 15 000, standard 4 000. För meshy-t2.5: intervall 100 till 30 000, standard 15 000.

Name
symmetry_mode
Type
string
⚠ föråldrad
standard auto
Description
Föråldrad. Denna parameter påverkar inte längre resultatet.
Fältet symmetry_mode styr symmetribeteendet under modellgenereringsprocessen.
Giltiga värden är:
- off: Inaktiverar symmetri.
- auto: Bestämmer och tillämpar symmetri automatiskt baserat på indatageometrin.
- on: Tvingar fram symmetri under generering.
Name
pose_mode
Type
string
standard ""
Description
Ange pose-mode för den genererade modellen.
Tillgängliga värden:
- a-pose: Generera modellen i en A-pose.
- t-pose: Generera modellen i en T-pose.
- "" (tom sträng): Ingen specifik pose tillämpas.
Name
is_a_t_pose
Type
boolean
⚠ föråldrad
standard false
Description
Använd pose_mode istället. Om modellen ska genereras i en A/T-pose.
Name
surface_mode
Type
string
⚠ föråldrad
Description
Påverkar inte längre resultatet. Den valde en modellgenerering som sedan har avvecklats; använd ai_model istället.
Godkända värden är organic och hard; alla andra värden returnerar 400.
Name
image_enhancement
Type
boolean
standard true
Description
Optimerar indatabilden för bättre resultat. Sätt till false för att bevara indatabildens exakta utseende utan någon stilbearbetning.
Stöds endast när ai_model är meshy-6, meshy-7.1 eller latest. Om den sätts med meshy-6-lite eller med model_type: smart-topology returneras ett fel.
Name
remove_lighting
Type
boolean
standard true
Description
Tar bort highlights och skuggor från basfärgstexturen, vilket ger ett renare resultat som fungerar bättre med anpassade ljussättningar.
Har endast effekt när ai_model är meshy-6. meshy-7.1 och latest accepterar parametern men ignorerar den. Om den sätts med meshy-6-lite eller med model_type: smart-topology returneras ett fel.
Name
moderation
Type
boolean
standard false
Description
När värdet sätts till true granskas indatainnehållet automatiskt för potentiellt skadligt innehåll. Om skadligt innehåll upptäcks kommer uppgiften inte att fortsätta till generering.
Innehållet från indata image_url, texture_image_url och texture_prompt kommer att granskas.
Name
target_formats
Type
string[]
Description
Anger vilka 3D-filformat som ska ingå i resultatet. Endast de begärda formaten kommer att genereras och returneras, vilket kan minska tiden det tar att slutföra uppgiften. Om parametern utelämnas inkluderas alla format som stöds.
Tillgängliga värden: glb, obj, fbx, stl, usdz, 3mf
Om parametern utelämnas genereras alla format utom 3mf. 3mf inkluderas endast när den uttryckligen anges.
Name
auto_size
Type
boolean
standard false
Description
När värdet sätts till true använder tjänsten AI-vision för att automatiskt uppskatta objektets verkliga höjd och ändrar modellens storlek därefter. Origo kommer som standard att vara bottom om inte origin_at uttryckligen anges.
Name
alpha_thumbnail
Type
boolean
standard false
Description
När värdet sätts till true renderar uppgiften dessutom en version av förhandsgranskningen med transparent bakgrund (RGBA) och returnerar den som alpha_thumbnail_url i GET-svaret. Det befintliga fältet thumbnail_url förblir oförändrat.
Name
multi_view_thumbnails
Type
boolean
standard false
Description
När värdet sätts till true renderar uppgiften dessutom fyra miniatyrer från huvudvyer (fram, höger, bak, vänster) och returnerar dem under thumbnail_urls i GET-svaret. Det befintliga fältet thumbnail_url är oförändrat och pekar fortfarande på framvyn, så befintliga klienter påverkas inte.
Lägger till ungefär 3 sekunder till uppgiftens svarstid.

Gäller endast när auto_size = true

Name
origin_at
Type
string
standard bottom
Description
Origots position när auto_size är aktiverat.
Tillgängliga värden: bottom, center.

Returnerar

Svarets result-egenskap innehåller uppgifts-id:t för den nyskapade Bild till 3D-uppgiften.

Felscenarier

Name
400 - Bad Request
Description
Förfrågan var inte godtagbar. Vanliga orsaker:
- Saknad parameter: Antingen image_url eller input_task_id måste anges.
- Ogiltig indatauppgift: input_task_id måste referera till en SUCCEEDED Text till bild- eller Bild till bild-uppgift som producerar exakt en bild.
- Ogiltigt bildformat: Den angivna image_url har inte ett format som stöds (.jpg, .jpeg, .png, .webp).
- Onåbar URL: image_url kunde inte laddas ner (404 eller timeout).
- Bild för stor: Bilden i image_url eller texture_image_url överskrider 20 MB.
- Ogiltig Data URI: Base64-strängen är felformaterad.
- Ogiltig parameterkombination: enable_pbr stöds endast när should_texture är true.
- Modell stöds inte för low poly: ai_model: "meshy-6-lite" stöder inte model_type: "lowpoly".
- Modell stöds inte för Ultra: geometry_resolution kräver meshy-7.1 eller latest.
- Modell stöds inte för bildalternativ: image_enhancement eller remove_lighting är satt med ai_model: "meshy-6-lite" eller model_type: "smart-topology".
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/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

Hämta en Bild till 3D-uppgift

Denna endpoint låter dig hämta en Bild till 3D-uppgift givet ett giltigt uppgifts-id. Se The Image to 3D Task Object för att se vilka egenskaper som ingår i Bild till 3D-uppgiftsobjektet.

Parametrar

Name
id
Type
path
Description
Unik identifierare för Bild till 3D-uppgiften som ska hämtas.

Returnerar

Svaret innehåller Bild till 3D-uppgiftsobjektet. Se avsnittet The Image to 3D Task Object för detaljer.

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

Ta bort en Bild till 3D-uppgift

Denna endpoint tar permanent bort en Bild till 3D-uppgift, inklusive alla tillhörande modeller och data. Denna åtgärd är oåterkallelig.

Sökvägsparametrar

Name
id
Type
path
Description
ID:t för den Bild till 3D-uppgift som ska tas bort.

Uppgiftsstatus

En uppgift som fortfarande är PENDING tas bort och de credits som förbrukades vid skapandet återbetalas.

En uppgift som redan är IN_PROGRESS kan inte tas bort: förfrågan avvisas med 409 Conflict och uppgiften fortsätter att köras. Credits för en uppgift som arbetaren redan har påbörjat är inte återbetalningsbara, så att ta bort den mitt under körningen skulle kosta dig både credits och resultatet. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, och ta sedan bort den.

En uppgift i ett sluttillstånd (SUCCEEDED, FAILED eller CANCELED) tas bort utan återbetalning.

Returvärden

Returnerar 200 OK vid lyckad borttagning, eller 409 Conflict när uppgiften är IN_PROGRESS.

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

Lista uppgifter för Bild till 3D

Denna endpoint låter dig hämta en lista med uppgifter för Bild till 3D.

Parametrar

Valfria attribut

Name
page_num
Type
integer
Description
Sidnummer för paginering. Börjar och har som standard 1.
Name
page_size
Type
integer
Description
Gräns för sidstorlek. Standardvärdet är 10 objekt. Maximalt tillåtet är 100 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 med uppgiftsobjekt för Bild till 3D.

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

Strömma en Bild till 3D-uppgift

Denna endpoint strömmar uppdateringar i realtid för en Bild till 3D-uppgift med hjälp av Server-Sent Events (SSE).

Parametrar

Name
id
Type
path
Description
Unik identifierare för den Bild till 3D-uppgift som ska strömmas.

Returnerar

Returnerar en ström av The Image to 3D Task Objects som Server-Sent Events.

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

The Image to 3D Task Object

Image to 3D Task-objektet är en arbetsenhet som Meshy håller reda på för att generera en 3D-modell från en bild-indata. Objektet har följande egenskaper:

Egenskaper

Name
id
Type
string
Description
Unik identifierare för uppgiften. Även om vi använder en k-sorterbar UUID för uppgifts-id:n som implementationsdetalj bör du inte göra några antaganden om id:ts format.
Name
type
Type
string
Description
Typ av Image to 3D-uppgift. Värdet är image-to-3d.
Name
model_urls
Type
object
Description
Nedladdningsbar URL till den texturerade 3D-modellfilen som genererats av Meshy. Egenskapen för ett format utelämnas om formatet inte genereras, istället för att returnera en tom sträng.
- 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-export 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 med när 3mf begärdes via target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Nedladdningsbar URL till den ursprungliga GLB-utdatan innan remeshing.
  Tillgänglig endast när uppgiften skapades med både should_remesh: true och save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
Nedladdningsbar URL till miniatyrbilden för modellfilen. Motsvarar thumbnail_urls.front när den finns, bibehålls för bakåtkompatibilitet.
Name
alpha_thumbnail_url
Type
string
Description
Nedladdningsbar URL till en version av thumbnail_url med transparent bakgrund (RGBA). Finns endast med när uppgiften skapades med alpha_thumbnail: true och den transparenta förhandsvisningen renderades korrekt; annars utelämnas detta fält.
Name
thumbnail_urls
Type
object
Description
Nedladdningsbara URL:er för fyra miniatyrbilder från huvudriktningarna av den genererade 3D-modellen. Varje värde är en signerad URL till en 512×512 PNG-bild renderad med samma material och belysning som thumbnail_url. Användbart för att förhandsgranska modellen från flera vinklar i batch-pipelines utan att ladda ner GLB-filen.
Finns endast med när uppgiften skapades med multi_view_thumbnails: true och har nått SUCCEEDED. Äldre uppgifter och uppgifter skapade utan denna inställning inkluderar inte detta fält.
- Name
  front
  Type
  string
  Description
  Framifrån, 0° rotation kring den vertikala axeln (motsvarar thumbnail_url).
- Name
  right
  Type
  string
  Description
  Höger vy, 90° rotation.
- Name
  back
  Type
  string
  Description
  Bakifrån, 180° rotation.
- Name
  left
  Type
  string
  Description
  Vänster vy, 270° rotation.
Name
texture_prompt
Type
string
Description
Textprompten som användes för att styra textureringsprocessen.
Name
texture_image_url
Type
string
Description
Nedladdningsbar URL till texturbilden som användes för att styra textureringsprocessen.
Name
ultra_mode
Type
boolean
⚠ föråldrad
Description
Föråldrad; läs geometry_resolution istället.
Name
geometry_resolution
Type
string
Description
Ultra-nivån som uppgiften kördes i (2k eller 4k); utelämnas för standard.
Name
progress
Type
integer
Description
Uppgiftens progress. Om uppgiften inte har startat ännu är denna egenskap 0. När uppgiften har lyckats blir den 100.
Name
started_at
Type
timestamp
Description
Tidsstämpel för när uppgiften startades, i millisekunder. Om uppgiften inte har startat ännu är denna egenskap 0.
En tidsstämpel representerar antalet millisekunder som har förflutit sedan den 1 januari 1970 UTC, enligt standarden RFC 3339. Till exempel representeras fredagen den 1 september 2023 kl. 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 avslutades, i millisekunder. Om uppgiften inte är avslutad ännu är denna egenskap 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 texture URL-objekt som genereras från uppgiften. Normalt innehåller denna bara ett texture URL-objekt. Varje texture URL har följande egenskaper:
- Name
  base_color
  Type
  string
  Description
  Nedladdningsbar URL till bildfilen för baskärgskartan.
- Name
  metallic
  Type
  string
  Description
  Nedladdningsbar URL till bildfilen för metalliskhetskartan.
  Om uppgiften skapades med enable_pbr: false utelämnas denna egenskap.
- Name
  normal
  Type
  string
  Description
  Nedladdningsbar URL till bildfilen för normalmappen.
  Om uppgiften skapades med enable_pbr: false utelämnas denna egenskap.
- Name
  roughness
  Type
  string
  Description
  Nedladdningsbar URL till bildfilen för ojämnhetskartan.
  Om uppgiften skapades med enable_pbr: false utelämnas denna egenskap.
- Name
  emission
  Type
  string
  Description
  Nedladdningsbar URL till bildfilen för emissionskartan.
  Om uppgiften skapades med enable_pbr: false, eller om ai_model är meshy-6-lite, meshy-7.1, meshy-t2 eller latest, utelämnas denna egenskap.
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter.
Värdet i detta fält är endast meningsfullt om uppgiftens status är PENDING.
Name
task_error
Type
object
Description
Felinformation för misslyckade uppgifter. Se Fel för den fullständiga referensen för task_error-objektet.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av denna uppgift. Finns med när uppgiftens status är PENDING, IN_PROGRESS eller SUCCEEDED. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid misslyckande).

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
}