Bild till 3D-API

Förvandla en bild till en 3D-modell, texturerad eller otexturerad, i de format du väljer. Skicka bilden, eller använd resultatet från en Text till bild- eller Bild till bild-uppgift.

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

Skapa en Bild till 3D-uppgift

Skapar en Bild till 3D-uppgift. Uppgiften körs i bakgrunden. För hur lång tid en uppgift vanligtvis tar, se Processing times.

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

# Textured with Meshy N1 from the input image
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",
    "texture_model": "meshy-n1"
  }'

Response

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

Parametrar

Name
input_task_id
Type
string
Obligatorisk
Description
Krävs om du inte skickar image_url. ID:t för en Text till Bild- eller Bild till Bild-uppgift vars bild du vill använda som indata. Uppgiften måste vara en du skapat med API:et, ha statusen SUCCEEDED, och ha skapat exakt en bild.

Name
image_url
Type
string
Obligatorisk
Description
Krävs om du inte skickar input_task_id. Bilden som ska omvandlas till en 3D-modell, som en offentlig URL eller en base64-kodad data-URI, till exempel data:image/jpeg;base64,<din base64-kodade bilddata>. Om du skickar båda använder Meshy input_task_id.
Bilden måste vara en JPG-, JPEG-, PNG- eller WebP-fil på högst 20 MB, minst 32 pixlar på varje sida, och högst 178 956 970 pixlar (bredd × höjd).

Name
model_type
Type
string
standard standard
Description
Vilken typ av 3D-nät som ska genereras.
Tillgängliga värden:
- standard: ett nät med hög detaljnivå
- smart-topology: ett nät från en Smart Topology-modell, som du väljer med ai_model (meshy-t2 eller meshy-t2.5)
Med smart-topology ignorerar Meshy should_remesh, save_pre_remeshed_model och decimation_mode, och accepterar endast topology: triangle.
Name
ai_model
Type
string
standard latest
Description
AI-modellen som genererar 3D-modellen. Tillgängliga värden beror på model_type.
Standardmodeller (model_type: standard):
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7 (föråldrad): använd meshy-7.1 istället
Smart Topology-modeller (model_type: smart-topology) ger trianglar, vid ett antal ytor du kan ställa in med target_polycount:
- meshy-t2: renare topology och naturligt separerade delar
- meshy-t2.5 (standard): skarpare detaljer för spelassets
Name
geometry_resolution
Type
string
standard standard
Description
Passeringen för geometrigenerering.
Tillgängliga värden:
- standard
- 2k: kör Ultra-passeringen vid 2048³
- 4k: kör Ultra-passeringen vid 4096³, för mest ytdetalj
2k kräver meshy-7.1, latest, eller den föråldrade meshy-7. 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 är detsamma som geometry_resolution: "2k".
Name
should_texture
Type
boolean
standard true
Description
Om texturer ska genereras. true returnerar en texturerad modell, och false hoppar över texturering och returnerar ett otexturerat nät.

Gäller endast när should_texture = true

Name
texture_model
Type
string
standard depends on ai_model
Description
AI-modellen som texturerar 3D-modellen, i samma uppgift. Utelämna den för att använda standardtexturmodellen för din ai_model. Det ändrar inte credits-kostnaden.
Tillgängliga värden:
- meshy-7: Meshy 7, med PBR-mappar och texturer upp till 8K
- meshy-n1: Meshy N1, en 2K-baskulörstextur enbart från referensbilder
- meshy-6-lite: Meshy 6 Lite, en 2K-textur till lägsta kostnad
- meshy-6: Meshy 6, endast som standard för ai_model: meshy-6
Varje ai_model accepterar meshy-7, meshy-n1 och meshy-6-lite. Ett alternativ som den valda texturmodellen inte stöder returnerar 400. Med meshy-n1 misslyckas uppgiften om en genererad modell har över 7 999 999 trianglar, och Meshy återbetalar dess credits. Med should_texture: false ignorerar Meshy texture_model, men ett okänt värde returnerar ändå 400.
Se Models för vad varje texturmodell gör och vilken du bör välja.
Name
enable_pbr
Type
boolean
standard false
Description
Om PBR-mappar (metallic, roughness och normal) också ska genereras utöver baskulören. true kräver should_texture: true, och returnerar 400 med should_texture: false. Med texture_model: meshy-n1 returnerar true 400.
Texturmodellen Meshy 6 genererar även en emission map, förutom vid texture_resolution: 8k.
Name
texture_resolution
Type
string
standard 2k
Description
Storleken på baskulörstexturen. En större textur fångar mer ytdetalj.
Tillgängliga värden:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
4k och 8k kräver texturmodellen Meshy 7 eller Meshy 6, och returnerar 400 med de andra. Vid 8k genererar Meshy ingen emission map.
Name
hd_texture
Type
boolean
⚠ föråldrad
standard false
Description
Använd texture_resolution istället. hd_texture: true är detsamma som texture_resolution: "4k". Om du skickar båda använder Meshy texture_resolution.
Name
texture_prompt
Type
string
Description
Text som styr texturen, upp till 800 tecken. Längre text returnerar 400. Med texture_model: meshy-n1 returnerar en sådan sändning 400.
Name
texture_image_url
Type
string
Description
En bild som styr texturen, som en offentlig URL eller en base64-kodad data-URI, till exempel data:image/jpeg;base64,<din base64-kodade bilddata>. Bilden måste vara en JPG-, JPEG-, PNG- eller WebP-fil på högst 20 MB, minst 32 pixlar på varje sida, och högst 178 956 970 pixlar (bredd × höjd).
Meshy styr texturen med endast en av texture_prompt och texture_image_url. Om du skickar båda använder Meshy texture_prompt. För credits-kostnaden för texturering, se Pricing.
Med texture_model: meshy-n1 texturerar Meshy utifrån den här bilden som framvy, eller från indatabilden när du utelämnar den.
Texturering utifrån en bild fungerar kanske inte bra när bildens form skiljer sig mycket från 3D-modellens geometri.

Name
should_remesh
Type
boolean
standard true (meshy-6-lite), false (other models)
Description
Om remesh-fasen ska köras. För den högsta kvaliteten på 3D-modellen, ställ in den till false.

Gäller endast när should_remesh = true

Name
topology
Type
string
standard triangle
Description
Ytatypen för den ommeshade modellen.
Tillgängliga värden:
- quad: ett övervägande quad-baserat nät
- triangle: ett decimerat triangelnät
Smart Topology-utdata är endast triangelbaserad, så quad med meshy-t2 eller meshy-t2.5 returnerar 400. Med texture_model: meshy-n1 returnerar quad 400 när modellen remeshas, vilket meshy-6-lite gör som standard.
Name
decimation_mode
Type
integer
Description
Adaptivt antal ytor, per nivå. När du ställer in den ignorerar Meshy target_polycount.
Tillgängliga värden:
- 1: ultra
- 2: hög
- 3: medel
- 4: låg
Name
save_pre_remeshed_model
Type
boolean
standard false
Description
Om en GLB av modellen från innan remesh-fasen också ska lagras. Meshy returnerar den i model_urls.pre_remeshed_glb.

Name
target_polycount
Type
integer
Description
Antalet ytor att sikta mot. Resultatet kan skilja sig från målet, beroende på modellens geometri.
Det gäller i två separata fall:
- Remesh: När should_remesh är true på en standard-modell decimerar Meshy nätet till ungefär detta antal. Om du ställer in decimation_mode använder Meshy den och ignorerar target_polycount.
- Smart Topology: När model_type är smart-topology och ai_model är meshy-t2 eller meshy-t2.5, genererar Meshy modellen med detta antal ytor. Ingen remesh körs, och du behöver inte should_remesh.
Intervallet och standardvärdet beror på fallet:
Fall Intervall Standard
Remesh 100 till 300000 30000
meshy-t2 100 till 15000 4000
meshy-t2.5 100 till 30000 15000
Ett värde utanför intervallet returnerar 400.

Fall	Intervall	Standard
Remesh	`100` till `300000`	`30000`
`meshy-t2`	`100` till `15000`	`4000`
`meshy-t2.5`	`100` till `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ föråldrad
standard auto
Description
Utelämna den, eftersom den inte påverkar resultatet. Dess värden styrde symmetri under generering:
- off: ingen symmetri
- auto: symmetri vald utifrån indatageometrin
- on: framtvingad symmetri
Name
pose_mode
Type
string
standard ""
Description
Posen för den genererade modellen.
Tillgängliga värden:
- a-pose: en A-pose
- t-pose: en T-pose
- "" (tom sträng): ingen specifik pose
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- eller T-pose.
Name
surface_mode
Type
string
⚠ föråldrad
Description
Använd ai_model istället. Den påverkar inte resultatet, eftersom den modellgenerering den valde är avvecklad.
Accepterade värden är organic och hard. Alla andra värden returnerar 400.
Name
image_enhancement
Type
boolean
standard true
Description
Om indatabilden ska optimeras innan generering. false behåller indatabildens exakta utseende, utan stilbehandling.
Den fungerar endast med meshy-6, meshy-7.1, eller latest. Med meshy-6-lite eller model_type: smart-topology returnerar den 400.
Name
remove_lighting
Type
boolean
standard true
Description
Om glansljus och skuggor ska tas bort från baskulörstexturen. Resultatet blir renare och fungerar bättre under din egen belysning.
Den har endast effekt med texturmodellen Meshy 6, och en texturmodell som inte stöder den returnerar 400 för true. Med model_type: smart-topology, eller med ai_model: meshy-6-lite och dess standardtexturmodell, returnerar en sådan sändning 400.
Name
moderation
Type
boolean
standard false
Description
Om dessa indata ska granskas för skadligt innehåll innan generering:
- image_url
- texture_image_url
- texture_prompt
Om Meshy upptäcker skadligt innehåll returnerar förfrågan 400 och Meshy skapar ingen uppgift.
Name
target_formats
Type
string[]
Description
Filformaten som ska genereras. Meshy genererar och returnerar endast de format du listar, vilket kan korta ner uppgiften. Om du utelämnar den genererar Meshy alla format utom 3mf, som du bara får när du listar den.
Tillgängliga värden:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
standard false
Description
Om objektets verkliga höjd ska uppskattas med AI-synfunktion och modellen anpassas till den. Meshy placerar origo vid botten om du inte ställer in origin_at.
Name
alpha_thumbnail
Type
boolean
standard false
Description
Om en förhandsvisning med transparent bakgrund (RGBA) också ska renderas, returnerad i alpha_thumbnail_url när du hämtar uppgiften. thumbnail_url ändras inte.
Name
multi_view_thumbnails
Type
boolean
standard false
Description
Om förhandsvisningar från fram, höger, bak och vänster också ska renderas, returnerade i thumbnail_urls när du hämtar uppgiften. thumbnail_url ändras inte och visar fortfarande framvyn. Detta lägger till ungefär 5 sekunder till uppgiften.

Gäller endast när auto_size = true

Name
origin_at
Type
string
standard bottom
Description
Var modellens origo ska placeras, bottom eller center.

Returnerar

Fältet result i svaret innehåller ID:t för den nya Bild till 3D-uppgiften.

Felscenarier

Name
400 - Bad Request
Description
Förfrågan kan inte köras. Felmeddelandet anger vilket problem som hittades. Till exempel:
- Saknad parameter: Varken image_url eller input_task_id skickades.
- Ogiltig indatauppgift: input_task_id är inte en SUCCEEDED Text till Bild- eller Bild till Bild-uppgift som skapade exakt en bild.
- Ogiltigt bildformat: image_url-bilden är inte en JPG-, JPEG-, PNG- eller WebP-fil.
- Onåbar URL: Meshy kan inte hämta image_url-bilden, eftersom URL:en returnerar 404 eller tidsgränsen överskrids.
- För stor bild: image_url- eller texture_image_url-bilden är över 20 MB.
- Ogiltig bildstorlek: image_url- eller texture_image_url-bilden har en sida kortare än 32 pixlar, eller fler än 178 956 970 pixlar (bredd × höjd).
- Ogiltig data-URI: base64-strängen är felformaterad.
- Ogiltig parameterkombination: enable_pbr är true, och should_texture är false.
- Modell stöds inte för Ultra: geometry_resolution är 2k eller 4k, med en ai_model som inte kan köra det.
- Modell stöds inte för bildalternativ: en av dessa:
  - image_enhancement skickades med ai_model: "meshy-6-lite" eller model_type: "smart-topology".
  - remove_lighting skickades med model_type: "smart-topology", eller med ai_model: "meshy-6-lite" och dess standardtexturmodell.
- Ogiltig texturmodell: texture_model är inte ett av de tillgängliga värdena.
- Texturmodell inte tillgänglig: texture_model är meshy-6 med en annan ai_model än meshy-6. Skicka meshy-7, meshy-n1 eller meshy-6-lite, eller utelämna den.
- Alternativ som inte stöds för texturmodellen: Förfrågan begär ett alternativ från texturmodellen som den inte stöder, till exempel enable_pbr: true med meshy-n1 eller en 4k-textur med meshy-6-lite. Se Models.
Åtgärda förfrågan och skicka den igen. Se Errors.
Name
401 - Unauthorized
Description
API-nyckeln saknas eller är ogiltig. Kontrollera Authorization-huvudet.
Name
402 - Payment Required
Description
Till exempel:
- Otillräckliga credits: Kontot har inte tillräckligt med credits för den här uppgiften, eller kontot har nått en credits-gräns. Kontrollera ditt credits-saldo och försök sedan igen.
- Gratisplan: Att skapa en uppgift kräver en betald plan. Uppgradera din plan i dina prenumerationsinställningar, och försök sedan igen.
Name
403 - Forbidden
Description
Innehållsmoderering blockerade prompten eller en indatabild. Ändra indata och försök sedan igen.
Name
404 - Not Found
Description
input_task_id matchar inga av dina uppgifter. Kontrollera uppgifts-ID:t och skicka sedan förfrågan igen.
Name
429 - Too Many Requests
Description
Du överskred din hastighetsgräns. Vänta och försök sedan igen. Se Rate limits.

Hämta en Bild till 3D-uppgift

Returnerar en Bild till 3D-uppgift baserat på dess ID.

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": null,
  "consumed_credits": 30
}

Parametrar

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

Returnerar

Bild till 3D-uppgiftsobjektet.

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

Ta bort en Bild till 3D-uppgift

Tar bort en Bild till 3D-uppgift permanent, inklusive dess modeller och data. Du kan inte ångra en borttagning.

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 keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

Sökvägsparametrar

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

Uppgiftsstatus

Att ta bort en uppgift med status PENDING återbetalar de credits som användes när du skapade den.

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

Att ta bort en uppgift med en slutgiltig status (SUCCEEDED, FAILED eller CANCELED) återbetalar inte dess credits.

Returvärden

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

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

Lista Bild till 3D-uppgifter

Returnerar en lista över dina Bild till 3D-uppgifter.

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": null,
    "consumed_credits": 30
  }
]

Parametrar

Name
page_num
Type
integer
standard 1
Description
Sidnumret som ska returneras, upp till 255. Ett högre värde returnerar 400.
Name
page_size
Type
integer
standard 10
Description
Antal uppgifter per sida, upp till 100.
Name
sort_by
Type
string
Description
Sorteringsordningen.
Tillgängliga värden:
- +created_at: äldsta först
- -created_at: nyaste först

Returer

En paginerad lista med Bild till 3D-uppgiftsobjekt.

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

Strömma en Bild till 3D-uppgift

Strömmar uppdateringar för en Bild till 3D-uppgift som Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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": null,
  "consumed_credits": 30
}

Parametrar

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

Returnerar

En ström av Bild till 3D-uppgiftsobjekt som Server-Sent Events.

Varje händelse innehåller hela uppgiftsobjektet, i samma format som Get-endpointen returnerar. Medan uppgiften är PENDING eller IN_PROGRESS har dess resultatfält inga värden ännu.

Image to 3D-task-objektet

Ett Image to 3D-task-objekt beskriver en generering av en 3D-modell från en bild. Det innehåller status, progress och modellfilerna när tasken lyckas.

Egenskaper

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": null,
  "consumed_credits": 30
}

Name
id
Type
string
Description
Task-ID:t. Behandla det som en opak sträng och förlita dig inte på dess format.
Name
type
Type
string
Description
Tasktypen, alltid image-to-3d.
Name
model_urls
Type
object
Description
Nedladdnings-URL:er för den genererade 3D-modellen, en per filformat. Ett format som tasken inte genererade saknar nyckel, i stället för en tom sträng.
- Name
  glb
  Type
  string
  Description
  GLB-filen.
- Name
  fbx
  Type
  string
  Description
  FBX-filen.
- Name
  obj
  Type
  string
  Description
  OBJ-filen.
- Name
  usdz
  Type
  string
  Description
  USDZ-filen.
- Name
  mtl
  Type
  string
  Description
  MTL-filen, returneras tillsammans med en OBJ-fil när modellen har texturer.
- Name
  stl
  Type
  string
  Description
  STL-filen.
- Name
  3mf
  Type
  string
  Description
  3MF-filen. Finns endast när target_formats innehåller 3mf.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  GLB-filen från innan remesh. Finns endast när du skapade tasken med både should_remesh: true och save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
Nedladdnings-URL för en förhandsgranskningsbild av 3D-modellen. När thumbnail_urls finns är det samma bild som thumbnail_urls.front. Meshy behåller den för bakåtkompatibilitet.
Name
alpha_thumbnail_url
Type
string
Description
Nedladdnings-URL för en version av thumbnail_url med transparent bakgrund (RGBA). Finns endast när du skapade tasken med alpha_thumbnail: true och Meshy renderade den transparenta förhandsgranskningen.
Name
thumbnail_urls
Type
object
Description
Nedladdnings-URL:er för förhandsgranskningar av 3D-modellen från fyra sidor. Varje värde är en signerad URL till en 512×512 PNG, renderad med samma material och belysning som thumbnail_url. Använd dem för att förhandsgranska modellen från flera vinklar, till exempel i en batch-pipeline, utan att ladda ner GLB-filen.
Finns endast när du skapade tasken med multi_view_thumbnails: true och tasken nådde SUCCEEDED. Tasks som skapats utan multi_view_thumbnails: true innehåller inte detta fält.
- Name
  front
  Type
  string
  Description
  Vyn framifrån, vid 0° runt den vertikala axeln. Den motsvarar thumbnail_url.
- Name
  right
  Type
  string
  Description
  Vyn från höger, vid 90°.
- Name
  back
  Type
  string
  Description
  Vyn bakifrån, vid 180°.
- Name
  left
  Type
  string
  Description
  Vyn från vänster, vid 270°.
Name
texture_prompt
Type
string
Description
Textprompten som styrde texturen.
Name
texture_image_url
Type
string
Description
Nedladdnings-URL för bilden som styrde texturen.
Name
ultra_mode
Type
boolean
⚠ föråldrad
Description
Läs geometry_resolution i stället.
Name
geometry_resolution
Type
string
Description
Ultra-nivån som tasken kördes med, 2k eller 4k. En standard-task innehåller inte detta fält.
Name
progress
Type
integer
Description
Hur stor del av tasken som är klar, i procent. Det är 0 tills tasken startar och 100 när den lyckas.
Name
started_at
Type
timestamp
Description
Tidpunkten då tasken startade, i Unix-millisekunder. Det är 0 tills tasken startar.
Name
created_at
Type
timestamp
Description
Tidpunkten då tasken skapades, i Unix-millisekunder.
Name
expires_at
Type
timestamp
Description
Tidpunkten då taskens resultat upphör att gälla, i Unix-millisekunder.
Name
finished_at
Type
timestamp
Description
Tidpunkten då tasken avslutades, i Unix-millisekunder. Det är 0 tills tasken avslutas.
Name
status
Type
string
Description
Taskstatusen, en av PENDING, IN_PROGRESS, SUCCEEDED, FAILED eller CANCELED.
Name
texture_urls
Type
array
Description
Texturmapparna som tasken genererade, som en array av objekt. Den innehåller vanligtvis ett objekt, med dessa fält:
- Name
  base_color
  Type
  string
  Description
  Nedladdnings-URL för grundfärgskartan.
- Name
  metallic
  Type
  string
  Description
  Nedladdnings-URL för den metalliska kartan. Fältet saknas när du skapade tasken med enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  Nedladdnings-URL för normalmappen. Fältet saknas när du skapade tasken med enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  Nedladdnings-URL för grovhetskartan. Fältet saknas när du skapade tasken med enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  Nedladdnings-URL för emissionskartan. Meshy inkluderar den endast när du skapade tasken med allt följande:
  
  ai_model: meshy-6, med dess standardtexturmodell
  
  enable_pbr: true
  
  en texture_resolution på 2k eller 4k
Name
preceding_tasks
Type
integer
Description
Antalet tasks före denna i kön. Värdet är meningsfullt endast medan tasken är PENDING.
Name
task_error
Type
object
Description
Feldetaljerna när tasken misslyckas. Det är null om inte statusen är FAILED. Se Fel.
Name
consumed_credits
Type
integer
Description
Antalet credits som tasken använde. Finns när statusen är PENDING, IN_PROGRESS eller SUCCEEDED. Det är 0 för en FAILED-task, eftersom Meshy återbetalar credits när en task misslyckas.