Text till 3D API

Generera 3D-modeller från textprompter i din egen applikation.

Text till 3D fungerar i två steg. Först skapar du en preview-uppgift (mode: "preview") för att generera ett 3D-nät utan textur, så att du kan kontrollera formen. Sedan skickar du den lyckade preview-uppgiftens task-ID till en refine-uppgift (mode: "refine") för att textura nätet. Båda stegen använder samma endpoint.

POST/openapi/v2/text-to-3d

Skapa en Text till 3D-förhandsgranskningsuppgift

Skapar en Text till 3D-förhandsgranskningsuppgift, som genererar ett otexturerat 3D-nät (endast geometri) från en textprompt. Detta är det första steget i det tvåstegsarbetsflödet. När förhandsgranskningen har lyckats skickar du dess uppgifts-ID i en refine-uppgift för att textursätta nätet. Se Skapa en Text till 3D refine-uppgift. För hela svarsschemat, se Text till 3D-uppgiftsobjektet.

Uppgiften körs i bakgrunden. För information om hur lång tid en uppgift vanligtvis tar, se Bearbetningstider.

Request

POST

/openapi/v2/text-to-3d

# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

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

Parametrar

Name
mode
Type
string
Obligatorisk
Description
Steget i det tvåstegsarbetsflödet. Skicka preview för att skapa en förhandsgranskningsuppgift.
Name
prompt
Type
string
Obligatorisk
Description
Text som beskriver objektet som ska genereras, upp till 800 tecken. Längre text returnerar 400.
Name
model_type
Type
string
standard standard
Description
Typen av 3D-nät som ska genereras.
Tillgängliga värden:
- standard: ett högdetaljerat 3D-nät
- smart-topology: ett Smart Topology-nät. Välj modell med ai_model (meshy-t2 eller meshy-t2.5).
Med smart-topology ignorerar Meshy should_remesh och decimation_mode, och accepterar endast topology: triangle.
Name
ai_model
Type
string
standard latest
Description
AI-modellen som genererar 3D-modellen. De tillgängliga värdena beror på model_type.
Standardmodeller (model_type: standard):
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7 (föråldrad): skicka meshy-7.1 istället
Smart Topology-modeller (model_type: smart-topology):
- meshy-t2: renare topology, naturligt separerade delar, triangel-utdata och ett antal ytor som du anger med target_polycount
- meshy-t2.5 (standard): skarpare detaljer för spelassets, triangel-utdata och ett antal ytor som du anger med target_polycount
Se Modeller för vilken modell som passar ditt projekt, till exempel en spelkaraktär eller en 3D-utskrift.
Name
geometry_resolution
Type
string
standard standard
Description
Geometrigenereringspasset. Gäller endast förhandsgranskningsuppgifter. En refine med denna parameter returnerar 400.
Tillgängliga värden:
- standard
- 2k: kör Ultra-passet vid 2048³
- 4k: kör Ultra-passet vid 4096³, för finare ytdetaljer
2k kräver meshy-7.1, latest, eller den föråldrade meshy-7. 4k kräver meshy-7.1 eller latest. Andra modeller returnerar 400.
Name
ultra_mode
Type
boolean
⚠ föråldrad
standard false
Description
Skicka geometry_resolution istället. ultra_mode: true är detsamma som geometry_resolution: "2k".
Name
should_remesh
Type
boolean
standard true (meshy-6-lite), false (other models)
Description
Om modellen ska remeshas efter generering. För högsta möjliga kvalitet på 3D-modellen, skicka false.

Gäller endast när should_remesh = true

Name
topology
Type
string
standard triangle
Description
Ytstypen för den remeshade modellen.
Tillgängliga värden:
- quad: ett quad-dominerat nät
- triangle: ett decimerat triangelnät
Smart Topology-utdata är endast triangel. Att skicka quad med ai_model meshy-t2 eller meshy-t2.5 returnerar 400.
Name
decimation_mode
Type
integer
Description
Adaptivt ytantal, per nivå. När du anger detta ignorerar Meshy target_polycount.
Tillgängliga värden:
- 1: ultra
- 2: hög
- 3: medium
- 4: låg

Name
target_polycount
Type
integer
Description
Antalet ytor att sikta mot. Resultatet kan skilja sig från målet, beroende på geometrin. Det gäller i två separata fall:
- Remesh: med should_remesh: true på en standard-modell. Meshy remeshar (decimerar) nätet till ungefär detta antal. Om du anger decimation_mode använder Meshy det och ignorerar target_polycount.
- Smart Topology: med model_type: smart-topology och ai_model meshy-t2 eller meshy-t2.5. Meshy genererar modellen med detta antal ytor direkt. Ingen remesh körs, och du behöver inte should_remesh.
Följande tabell visar intervallet och standardvärdet för varje fall:
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.
För ett low-poly-spelasset, använd en Smart Topology-modell istället för att remesha en standardmodell. Se Modeller.

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. Denna parameter påverkar inte utdatan.
Tillgängliga värden:
- off: inaktiverar symmetri
- auto: tillämpar symmetri baserat på inmatningsgeometrin
- on: framtvingar symmetri under generering
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
Skicka pose_mode istället. Om modellen ska genereras i en A-pose eller en T-pose.
Name
art_style
Type
string
⚠ föråldrad
standard realistic
Description
Utelämna den. Meshy ignorerar den.
Name
moderation
Type
boolean
standard false
Description
Om prompt ska granskas för skadligt innehåll innan generering. Om Meshy upptäcker skadligt innehåll returnerar begäran 400 och Meshy skapar ingen uppgift.
Name
target_formats
Type
string[]
Description
Filformaten som ska genereras. Meshy genererar och returnerar endast dessa format, vilket kan korta ner uppgiften. Om du utelämnar den genererar Meshy alla format utom 3mf, som det endast genererar när du begär det.
Tillgängliga värden:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
standard false
Description
Om en förhandsgranskning med transparent bakgrund (RGBA) också ska renderas, returnerad i alpha_thumbnail_url när du hämtar uppgiften. thumbnail_url ändras inte.
Name
auto_size
Type
boolean
standard false
Description
Om objektets verkliga höjd ska uppskattas med AI-synförmåga och modellen ändra storlek till den. Meshy placerar origo vid botten om du inte anger origin_at.

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

Svarets result-fält innehåller ID:t för den nya Text till 3D-uppgiften.

Felfall

Name
400 - Bad Request
Description
Begäran kan inte köras. Felmeddelandet anger vilket problem som hittades. Till exempel:
- Saknad parameter: En obligatorisk parameter, till exempel prompt eller mode, saknas.
- Prompt för lång: prompt överskrider teckengränsen.
- Modell som inte stöds för Ultra: geometry_resolution är 2k eller 4k, med en ai_model som inte klarar av det.
Åtgärda begäran och skicka den igen. Se Fel.
Name
401 - Unauthorized
Description
API-nyckeln saknas eller är ogiltig. Kontrollera Authorization-headern.
Name
402 - Payment Required
Description
Till exempel:
- Otillräckliga credits: Kontot har inte tillräckligt med credits för denna uppgift, eller kontot har nått en credit-gräns. Kontrollera ditt credit-saldo och försök igen.
- Gratisplan: Att skapa en uppgift kräver en betald plan. Uppgradera din plan i dina prenumerationsinställningar, och försök igen.
Name
403 - Forbidden
Description
Innehållsmoderering blockerade prompten eller en inmatningsbild. Ändra inmatningen och försök igen.
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns. Vänta och försök igen. Se Hastighetsgränser.

POST/openapi/v2/text-to-3d

Skapa en Text till 3D refine-uppgift

Skapar en Text till 3D refine-uppgift, som texturerar nätet från en slutförd preview-uppgift. Skicka ID:t för en lyckad preview-uppgift som preview_task_id. Se Skapa en Text till 3D preview-uppgift. Detta är det andra steget i det tvåstegsflödet.

Uppgiften körs i bakgrunden. För information om hur lång tid en uppgift vanligtvis tar, se Bearbetningstider.

Request

POST

/openapi/v2/text-to-3d

# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

# Refine with Meshy N1 from the preview's stored reference image
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "ai_model": "meshy-n1"
}'

Response

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

Parametrar

Name
mode
Type
string
Obligatorisk
Description
Steget i det tvåstegsflödet. Skicka refine för att skapa en refine-uppgift.
Name
preview_task_id
Type
string
Obligatorisk
Description
ID:t för den preview-uppgift som ska textureras. Preview-uppgiften måste ha statusen SUCCEEDED.
Name
enable_pbr
Type
boolean
standard false
Description
Om PBR-mappar (metallic, roughness och normal) också ska genereras utöver grundfärgen.
Med ai_model meshy-6 genererar Meshy även en emissionsmapp, förutom vid texture_resolution: 8k. meshy-6-lite, meshy-7, meshy-7.1 och latest genererar ingen emissionsmapp. Det gör inte heller en refine av en meshy-t2- eller meshy-t2.5-preview som inte anger ai_model. Med ai_model: meshy-n1 ger true 400.
Name
texture_resolution
Type
string
standard 2k
Description
Upplösningen för grundfärgstexturen. Gäller endast refine-uppgifter. En preview med denna parameter ger 400.
Tillgängliga värden:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
Högre upplösningar fångar mer ytdetaljer. 4k och 8k kräver ai_model meshy-6, meshy-7.1 eller latest. Med meshy-n1 ger de 400. Vid 8k genererar Meshy ingen emissionsmapp.
Name
hd_texture
Type
boolean
⚠ föråldrad
standard false
Description
Skicka 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 textureringen, upp till 800 tecken. Längre text ger 400. Skicka texture_prompt eller texture_image_url, inte båda. Om du skickar båda använder Meshy texture_prompt. Med ai_model: meshy-n1 ger det 400 att skicka den.
Name
texture_image_url
Type
string
Description
En 2D-bild som styr textureringen, antingen som en offentlig URL eller en base64-kodad data-URI, till exempel data:image/jpeg;base64,<your base64-encoded image data>.
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).
Med ai_model: meshy-n1 texturerar Meshy utifrån denna bild som framsidesvy.
Texturering utifrån en bild fungerar kanske inte bra om formen i bilden skiljer sig mycket från modellen.
Name
ai_model
Type
string
standard inherited from the preview task
Description
AI-modellen som texturerar nätet.
Tillgängliga värden:
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-n1: en 2K-grundfärgstextur utifrån enbart en referensbild. Ingen textprompt, inga PBR-mappar, ingen 4K eller 8K.
- meshy-7 (föråldrad): skicka meshy-7.1 istället
Utelämna den för att använda preview-uppgiftens modell, så att preview och dess refine körs på samma modell från start till slut. Skicka ett värde för att åsidosätta det. Ett explicit latest löses på samma sätt som för preview-uppgiften, så en latest-preview och dess latest-refine använder alltid samma texturmodell.
Med meshy-n1 texturerar Meshy utifrån texture_image_url. Utan den använder Meshy den referensbild som en meshy-7.1- eller latest-preview lagrar. Alla andra preview-typer ger 400 om du inte skickar texture_image_url. Previewn kan ha högst 7 999 999 trianglar. En preview som remeshats till quads ger 400.
Name
moderation
Type
boolean
standard false
Description
Om texture_prompt och texture_image_url ska granskas för skadligt innehåll innan generering. Om Meshy upptäcker skadligt innehåll ger begäran 400 och Meshy skapar ingen uppgift.
Name
remove_lighting
Type
boolean
standard true
Description
Om högdagrar och skuggor ska tas bort från grundfärgstexturen. Det renare resultatet fungerar bättre under anpassad belysning.
Har endast effekt när ai_model är meshy-6. meshy-7.1 och latest accepterar den men ignorerar den, och det gör även en refine av en meshy-t2- eller meshy-t2.5-preview som inte anger ai_model. Att skicka den med meshy-6-lite ger 400. Med meshy-n1 ger true 400.
Name
target_formats
Type
string[]
Description
Filformaten som ska genereras. Meshy genererar och returnerar endast dessa format, vilket kan förkorta uppgiften. Om du utelämnar den genererar Meshy alla format utom 3mf, som den bara genererar om du begär det.
Tillgängliga värden:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
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
auto_size
Type
boolean
standard false
Description
Om objektets verkliga höjd ska uppskattas med AI-syn och modellen ska ändras i storlek till den. Meshy placerar origo vid botten om du inte anger origin_at.

Gäller endast när auto_size = true

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

Returvärden

Svarets result-fält innehåller ID:t för den nya Text till 3D-uppgiften.

Felscenarier

Name
400 - Bad Request
Description
Begäran kan inte köras. Felmeddelandet anger vilket problem det hittade. Till exempel:
- Ogiltigt uppgifts-ID: preview_task_id är ogiltigt eller matchar inte någon av dina preview-uppgifter.
- Uppgiften inte klar: Preview-uppgiften har ännu inte lyckats.
- Modellmismatch: Preview-uppgiftens AI-modell fungerar inte med den begärda refine-modellen.
- Modell saknar stöd för remove_lighting: remove_lighting skickades med ai_model: "meshy-6-lite".
- Ingen referensbild för Meshy N1: ai_model: meshy-n1 skickades utan texture_image_url, och previewn har ingen referensbild som Meshy N1 kan använda. Skicka texture_image_url.
- Quad-preview för Meshy N1: ai_model: meshy-n1 skickades för en preview som remeshats till quads. Utför refine med en annan ai_model.
- För många trianglar för Meshy N1: Med ai_model: meshy-n1 har previewn fler än 7 999 999 trianglar. Utför refine med en annan ai_model.
- Alternativ som inte stöds för Meshy N1: ai_model: meshy-n1 skickades med ett av följande alternativ:
  - texture_prompt
  - enable_pbr: true
  - texture_resolution på 4k eller 8k
  - hd_texture: true utan texture_resolution
  - remove_lighting: true
Åtgärda begäran och skicka den igen. Se Fel.
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 creditgräns. Kontrollera ditt saldo av credits 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 inmatningsbild. Ändra indata och försök sedan igen.
Name
429 - Too Many Requests
Description
Du överskred din hastighetsgräns. Vänta och försök sedan igen. Se Hastighetsgränser.

GET/openapi/v2/text-to-3d/:id

Hämta en Text till 3D-uppgift

Returnerar en Text till 3D-uppgift baserat på dess ID. Det fungerar för både preview- och refine-uppgifter.

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 20
}

Parametrar

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

Returnerar

Text till 3D-uppgiftsobjektet.

Exempel

Följande tabell visar en exempelmodell för varje mode.

Mode	Exempelmodell
Preview
Refine

DELETE/openapi/v2/text-to-3d/:id

Ta bort en Text till 3D-uppgift

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

Request

DELETE

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-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 PENDING-uppgift återbetalar de credits som användes när du skapade den.

En IN_PROGRESS-uppgift kan inte tas bort. Förfrågan returnerar 409 Conflict, och uppgiften fortsätter att köras. Meshy återbetalar inte en uppgift som har startat, 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 sluttatus (SUCCEEDED, FAILED eller CANCELED) återbetalar inte dess credits.

Returnerar

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

GET/openapi/v2/text-to-3d

Lista Text till 3D-uppgifter

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

Request

GET

/openapi/v2/text-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": null,

    "consumed_credits": 20
  }
]

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
Antalet 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

Returnerar

En sidindelad lista med Text till 3D-uppgiftsobjekt.

GET/openapi/v2/text-to-3d/:id/stream

Stream a Text to 3D task

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

Request

GET

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

curl -N https://api.meshy.ai/openapi/v2/text-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",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"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": 20
}

Parametrar

Name
id
Type
path
Description
Uppgifts-ID:t från svaret vid skapandet.

Returnerar

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

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

Text till 3D-task-objektet

Ett Text till 3D-task-objekt beskriver en task som genererar en 3D-modell från en text-prompt. Det innehåller status, progress och modellfilerna när task:en lyckas. Text till 3D har två steg, preview och refine. En preview-task genererar en 3D-modell med enbart nät, och en refine-task genererar en texturerad 3D-modell utifrån preview-resultatet.

Egenskaper

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "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": 20
}

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
Task-typen, text-to-3d-preview för en preview-task eller text-to-3d-refine för en refine-task.
Name
model_urls
Type
object
Description
Nedladdningslänkar för den genererade 3D-modellen, en per filformat. Ett format som task:en inte genererade saknar nyckel, istället för att ha en tom sträng.
- Name
  glb
  Type
  string
  Description
  GLB-filen.
- Name
  fbx
  Type
  string
  Description
  FBX-filen.
- Name
  usdz
  Type
  string
  Description
  USDZ-filen.
- Name
  obj
  Type
  string
  Description
  OBJ-filen.
- Name
  mtl
  Type
  string
  Description
  MTL-filen.
- Name
  stl
  Type
  string
  Description
  STL-filen.
- Name
  3mf
  Type
  string
  Description
  3MF-filen. Finns endast när target_formats innehåller 3mf.
Name
prompt
Type
string
Description
prompt du skickade för att skapa task:en, oförändrad.
Name
texture_prompt
Type
string
Description
Textprompten du skickade för att styra texturering i refine-steget.
Name
ultra_mode
Type
boolean
⚠ föråldrad
Description
Läs geometry_resolution istället.
Name
geometry_resolution
Type
string
Description
Ultra-nivån som preview-task:en kördes med, 2k eller 4k. Fältet saknas för standard.
Name
texture_image_url
Type
string
Description
Nedladdningslänk för bilden du skickade för att styra texturering.
Name
thumbnail_url
Type
string
Description
Nedladdningslänk för en miniatyrbild av 3D-modellen.
Name
alpha_thumbnail_url
Type
string
Description
Nedladdningslänk för en version av thumbnail_url med transparent bakgrund (RGBA). Finns endast när du skapade task:en med alpha_thumbnail: true och Meshy renderade den transparenta förhandsvisningen.
Name
progress
Type
integer
Description
Hur mycket av task:en som är klar, i procent. Det är 0 tills task:en startar och 100 när den lyckas.
Name
started_at
Type
timestamp
Description
Tiden då task:en startade, i Unix-millisekunder. Det är 0 tills task:en startar.
Name
created_at
Type
timestamp
Description
Tiden då task:en skapades, i Unix-millisekunder.
Name
finished_at
Type
timestamp
Description
Tiden då task:en avslutades, i Unix-millisekunder. Det är 0 tills task:en avslutas.
Name
status
Type
string
Description
Task-statusen, en av PENDING, IN_PROGRESS, SUCCEEDED, FAILED eller CANCELED.
Name
texture_urls
Type
array
Description
Nedladdningslänkar för de genererade texturkartorna, som en array av objekt. Den innehåller vanligtvis ett objekt. Varje objekt har dessa fält:
- Name
  base_color
  Type
  string
  Description
  Baskolorkartan.
- Name
  metallic
  Type
  string
  Description
  Metallic-kartan. Saknas när du skapade task:en med enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  Normalmapen. Saknas när du skapade task:en med enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  Roughness-kartan. Saknas när du skapade task:en med enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  Emission-kartan. Saknas i något av dessa fall:
  
  Du skapade task:en med enable_pbr: false.
  
  ai_model är meshy-6-lite, meshy-7, meshy-7.1 eller latest.
  
  texture_resolution är 8k.
  
  Task:en refinar en meshy-t2- eller meshy-t2.5-preview utan att ange ai_model.
Name
preceding_tasks
Type
integer
Description
Antalet tasks före denna i kön. Värdet är meningsfullt endast medan task:en är PENDING.
Name
task_error
Type
object
Description
Feldetaljerna när task:en misslyckas. Det är null om inte statusen är FAILED. Se Fel.
Name
consumed_credits
Type
integer
Description
Antalet credits som task:en förbrukade. 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.