Auto Split API

Dela upp en 3D-modell i separat utskrivbara delar — automatiskt, efter de delar du namnger, eller efter färgregion — med valfria kopplingar; tunna områden som lämnas kvar av ett snitt förstärks alltid så att varje del skrivs ut solid.

Auto Split stöder för närvarande endast otexturerade modeller. För Bild till 3D och Flera bilder till 3D, generera indatan med should_texture inställt på false. En texturerad indata avvisas med 400.

POST/openapi/v1/print/split

Skapa en Auto Split-uppgift

Denna endpoint skapar en ny Auto Split-uppgift. Uppgiften delar upp modellen från en tidigare uppgift i separat utskrivbara delar och returnerar den segmenterade modellen, där varje del är ett eget objekt i filen.

Parametrar

  • Name
    input_task_id
    Type
    string
    Obligatorisk
    Description

    ID:t för en lyckad uppgift vars modell ska delas upp. Uppgiftstyper som stöds: Bild till 3D, Flera bilder till 3D, Text till 3D (förhandsversion), Remesh, Konvertera och Ändra storlek. Uppgiften måste ha statusen SUCCEEDED, och dess modell måste vara genererad med Meshy 6 eller Meshy 7 (ai_model meshy-6, meshy-7, eller latest). Low-poly- och Smart Topology-modeller (meshy-t2) stöds inte.

  • Name
    mode
    Type
    string
    standard auto
    Description

    Hur modellen delas upp i delar.

    Tillgängliga värden:

    • auto: Meshy väljer snitten. prompt ignoreras.
    • by_parts: Skär längs de strukturella delar du namnger i prompt, till exempel huvud, armar och torso.
    • by_color: Skär längs de färgregioner du namnger i prompt. Kräver en indata som genererats från en uppladdad bild (Bild till 3D eller Flera bilder till 3D); andra indata avvisas med 400.
Gäller endast när mode = by_parts or by_color
  • Name
    prompt
    Type
    string
    Obligatorisk
    Description

    Beskriver de delar som ska delas upp i, på vilket språk som helst. Meshy läser 1 till 10 delnamn från den, så namnge delarna snarare än att beskriva modellen — till exempel split into the figure and the base, eller head, torso, left arm, right arm, legs. Upp till 600 tecken. Två sätt att misslyckas: en beskrivning som läses som en uppdelning men som namnger färre än två delar (till exempel split into individual parts) avvisas med 400 och inget debiteras; en beskrivning som Meshy inte alls kan tolka faller tillbaka till auto, uppgiften körs ändå och debiteras, och dess svar innehåller prompt_ignored: true.

  • Name
    target_formats
    Type
    array
    standard ["glb"]
    Description

    Format att exportera den uppdelade modellen i. Varje del är ett separat objekt i varje format. glb produceras alltid och returneras i model_urls; lista eventuella andra format du vill ha utöver detta.

    Tillgängliga värden: glb, obj, fbx, usdz, blend, 3mf.

  • Name
    layout
    Type
    string
    standard assembled
    Description

    Hur delarna är arrangerade i varje utdataformat, och i miniatyren.

    Tillgängliga värden:

    • assembled: Delarna behåller sina platser från källmodellen.
    • on_plate: Delarna läggs platt och utspridda på byggplattan, redo att skivas — samma arrangemang som webbappens On Plate-vy.

    I båda layouterna innehåller de exporterade filerna ett objekt per del och inget annat: en hoptryckt flisa eller punktliknande del som blivit kvar från ett snitt tas bort före exporten, så varje objekt du hittar i filen är utskrivbart.

  • Name
    connectors
    Type
    boolean
    standard false
    Description

    Lägger till tapp-och-hål-kopplingar vid varje snitt så att de utskrivna delarna passar ihop.

Gäller endast när connectors = true
  • Name
    connector_type
    Type
    string
    standard cube
    Description

    Formen på kopplingen vid varje snittyta.

    Tillgängliga värden: cube, cylinder.

  • Name
    connector_size
    Type
    number
    standard 0.5
    Description

    Kopplingens storlek i förhållande till snittytan.

    Giltigt intervall: 0.1 till 0.8.

  • Name
    connector_height
    Type
    number
    standard 0.1
    Description

    Hur långt kopplingen sträcker sig från snittytan, i förhållande till snittytan.

    Giltigt intervall: 0.1 till 0.8.

Returvärden

Egenskapen result i svaret innehåller id för den nyskapade Auto Split-uppgiften.

Felfall

  • Name
    400 - Bad Request
    Description

    Begäran var oacceptabel. Vanliga orsaker:

    • Saknad prompt: prompt krävs när mode är by_parts eller by_color.
    • Prompt namnger färre än två delar: by_parts / by_color kräver minst två namngivna delar (till exempel head, torso, base); en generisk instruktion som split into individual parts avvisas. Inget debiteras.
    • Uppgiftstyp som inte stöds: input_task_id måste referera till en lyckad uppgift av en typ som stöds, genererad med Meshy 6 eller Meshy 7.
    • Texturerad indata: Indatamodellen har texturer. Endast otexturerade modeller stöds för närvarande.
    • Ingen referensbild: by_color kräver en indata som genererats från en uppladdad bild.
    • Format som inte stöds: target_formats innehåller stl.
    • Koppling utanför intervallet: connector_size eller connector_height ligger utanför 0.1 till 0.8.
  • Name
    401 - Unauthorized
    Description

    Autentiseringen misslyckades. Kontrollera din API-nyckel.

  • Name
    402 - Payment Required
    Description

    Otillräckligt med credits för att utföra denna uppgift.

  • Name
    404 - Not Found
    Description

    input_task_id finns inte eller tillhör inte ditt konto.

  • Name
    429 - Too Many Requests
    Description

    Du har överskridit din hastighetsgräns. by_parts- och by_color-förfrågningar delar också en gräns för prompt-tolkning på 12 förfrågningar per minut och konto.

  • Name
    503 - Service Unavailable
    Description

    Promptbaserad uppdelning (by_parts och by_color) är tillfälligt otillgänglig. Försök igen senare, eller använd mode: "auto", som inte påverkas. Inget debiteras.

Request

POST
/openapi/v1/print/split
# Simple request: let Meshy choose the cuts
curl https://api.meshy.cn/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Advanced request: name the parts, add connectors, export glb and obj
curl https://api.meshy.cn/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "mode": "by_parts",
    "prompt": "split into the figure and the base",
    "target_formats": ["glb", "obj"],
    "layout": "on_plate",
    "connectors": true,
    "connector_type": "cylinder",
    "connector_size": 0.4
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/print/split/:id

Hämta en Auto Split-uppgift

Denna endpoint hämtar en Auto Split-uppgift utifrån dess ID.

Parametrar

  • Name
    id
    Type
    path
    Description

    ID för den Auto Split-uppgift som ska hämtas.

Returnerar

Auto Split Task-objektet.

Request

GET
/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl https://api.meshy.cn/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}
DELETE/openapi/v1/print/split/:id

Ta bort en Auto Split-uppgift

Denna endpoint tar permanent bort en Auto Split-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 Auto Split-uppgift som ska tas bort.

Returnerar

Returnerar 200 OK vid lyckad åtgärd.

Request

DELETE
/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl --request DELETE \
  --url https://api.meshy.cn/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.
GET/openapi/v1/print/split

Lista Auto Split-uppgifter

Denna endpoint låter dig hämta en lista över Auto Split-uppgifter.

Parametrar

Valfria attribut

  • Name
    page_num
    Type
    integer
    Description

    Sidnummer för paginering. Börjar på och har standardvärdet 1.

  • Name
    page_size
    Type
    integer
    Description

    Gräns för sidstorlek. Standardvärdet är 10 objekt. Maximalt tillåtet är 100 objekt; större värden begränsas till 100.

  • 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.

Returvärden

Returnerar en paginerad lista med The Auto Split Task Objects.

Request

GET
/openapi/v1/print/split
curl https://api.meshy.cn/openapi/v1/print/split?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-split",
    "model_urls": {
      "glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "part_count": 4,
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000082000,
    "task_error": null,
    "consumed_credits": 10
  }
]
GET/openapi/v1/print/split/:id/stream

Streama en Auto Split-uppgift

Denna endpoint strömmar realtidsuppdateringar för en Auto Split-uppgift med hjälp av Server-Sent Events (SSE).

Parametrar

  • Name
    id
    Type
    path
    Description

    Unik identifierare för den Auto Split-uppgift som ska strömmas.

Returer

Returnerar en ström av Auto Split Task-objekt som Server-Sent Events.

Varje message-händelse innehåller hela uppgiftsobjektet så som det returneras av Hämta en Auto Split-uppgift, inklusive consumed_credits, tidsstämplarna och prompt_ignored; medan uppgiften är PENDING eller IN_PROGRESS är fälten som ändras mellan bildrutorna progress, status, started_at och preceding_tasks, och model_urls, thumbnail_url, part_count och parts visas när den når SUCCEEDED. En error-händelse innehåller endast status_code och message, så gör en förgrening baserat på händelsenamnet innan du läser status.

Request

GET
/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.cn/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f/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 (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

The Auto Split Task Object

En Auto Split-uppgift innehåller endast egenskaperna nedan. Fälten för genereringsprompt som andra uppgiftsobjekt innehåller (name, object_prompt, texture_prompt och så vidare), det enskilda model_url, och texture_urls fylls aldrig i för en uppdelning och returneras inte. Egenskaper som fylls i medan uppgiften körs (thumbnail_url, model_urls, tidsstämplarna) finns alltid med, tomma tills de har ett värde, så uppsättningen nycklar ändras inte mellan PENDING och SUCCEEDED.

  • Name
    id
    Type
    string
    Description

    Unik identifierare för uppgiften. Även om vi använder en k-sorterbar UUID för uppgifts-id som implementationsdetalj bör du inte göra några antaganden om id:ts format.

  • Name
    type
    Type
    string
    Description

    Typ av uppgift. Värdet är print-split.

  • Name
    model_urls
    Type
    object
    Description

    Nedladdningsbara URL:er till den uppdelade modellen, en per begärt format. Varje del är ett separat objekt i filen. Egenskapen för ett format utelämnas om formatet inte begärdes.

    • Name
      glb
      Type
      string
      Description

      Nedladdningsbar URL till den uppdelade modellen i GLB-format.

    • Name
      obj
      Type
      string
      Description

      Nedladdningsbar URL till den uppdelade modellen i OBJ-format.

    • Name
      fbx
      Type
      string
      Description

      Nedladdningsbar URL till den uppdelade modellen i FBX-format.

    • Name
      usdz
      Type
      string
      Description

      Nedladdningsbar URL till den uppdelade modellen i USDZ-format.

    • Name
      blend
      Type
      string
      Description

      Nedladdningsbar URL till den uppdelade modellen i Blender-format.

    • Name
      3mf
      Type
      string
      Description

      Nedladdningsbar URL till den uppdelade modellen i 3MF-format.

  • Name
    thumbnail_url
    Type
    string
    Description

    Nedladdningsbar URL till en renderad förhandsvisning av den uppdelade modellen, med varje del i en distinkt färg, i den begärda layout.

  • Name
    prompt_ignored
    Type
    boolean
    Description

    true när en by_parts- eller by_color-förfrågans prompt inte namngav några delar, så Meshy delade upp modellen automatiskt istället — delnamnen i resultatet är Meshys, inte dina. Finns med från och med PENDING. Utelämnas för auto-uppgifter och närhelst prompten följdes.

  • Name
    part_count
    Type
    integer
    Description

    Antal utskrivbara delar i den uppdelade modellen — en per objekt i de exporterade filerna. Kollapsade flisor som segmenteringen inte kunde göra till en utskrivbar del tas bort från filerna före export och räknas inte.

  • Name
    progress
    Type
    integer
    Description

    Progress för uppgiften. Om uppgiften inte har startats ännu blir denna egenskap 0. När uppgiften har lyckats blir den 100.

  • Name
    status
    Type
    string
    Description

    Status för uppgiften. Möjliga värden är ett av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • 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
    created_at
    Type
    timestamp
    Description

    Tidsstämpel för när uppgiften skapades, i millisekunder.

  • Name
    started_at
    Type
    timestamp
    Description

    Tidsstämpel för när uppgiften startades, i millisekunder. Om uppgiften inte har startats ännu blir denna egenskap 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tidsstämpel för när uppgiften avslutades, i millisekunder. Om uppgiften inte har avslutats ännu blir denna egenskap 0.

  • Name
    task_error
    Type
    object
    Description

    Feldetaljer för misslyckade uppgifter. Se Fel för den fullständiga referensen till task_error-objektet.

  • Name
    consumed_credits
    Type
    integer
    Description

    Antalet credits som förbrukats av denna uppgift. Finns alltid med: 10 när uppgiften har accepterats, och 0 för FAILED-uppgifter eftersom avgiften återbetalas vid misslyckande. Om en uppgift raderas medan den fortfarande är PENDING återbetalas den också.

The Auto Split Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}