Creative Lab — Collapsible Fidget API

Förvandla ett källfoto till en hopfällbar fidget-leksak som skrivs ut redo att användas: motivets siluett blir en uppsättning nästlade koncentriska ringar som kan fällas ihop platt och sträckas ut igen, utskriven i ett enda stycke utan montering.

  • POST /openapi/creative-lab/fidget-collapsible/v1

Till skillnad från de andra Creative Lab-endpointerna har den här inget par av prototyp-/byggsteg — det finns inga mellanliggande kandidater att välja mellan, så en enda uppgift tar bilden hela vägen till en 3D-modell. Geometrikontrollerna som webbappen exponerar (storlek, antal lager, gapbredd, väggtjocklek, extruderingsdjup, utbuktning) är inte heller en del av begäran: varje uppgift byggs med samma standardvärden på serversidan.


POST/openapi/creative-lab/fidget-collapsible/v1

Skapa en Collapsible Fidget-uppgift

Generera en collapsible fidget-modell från ett källfoto. Se The Collapsible Fidget Task Object för svarets format.

Varje uppgift kostar 6 credits och kräver en betald plan.

Parametrar

  • Name
    image_url
    Type
    string
    Obligatorisk
    Description

    Källfoto som Meshy ska omvandla till en collapsible fidget. Vi stöder för närvarande formaten .jpg, .jpeg, .png och .webp.

    Det finns två sätt att tillhandahålla bilden:

    • Publikt tillgänglig URL: En URL som är tillgänglig från det publika internet.
    • Data URI: En base64-kodad data URI av bilden. Exempel på en data URI: data:image/jpeg;base64,<your base64-encoded image data>.

    Ett motiv med en tydlig, sluten kontur fungerar bäst — silhuetten är det som blir ringarna. Rörig bakgrund, flera separata motiv eller mycket tunna former kan lämna för lite yta för de nästlade väggarna, och uppgiften misslyckas med ett uppgiftsfel.

  • Name
    name
    Type
    string
    Description

    Valfritt uppgiftsnamn för visningsändamål. Maximalt 100 tecken. Detta är endast en uppgiftsetikett; ingenting graveras på modellen.

Returer

Svarets egenskap result innehåller uppgifts-id för den nyskapade collapsible fidget-uppgiften. Fråga Get a Task-endpointen eller prenumerera på strömmen tills uppgiften når SUCCEEDED, ladda sedan ner den utskrivbara STL-filen från model_urls.stl (och, när den finns, GLB-filen från model_urls.glb för att förhandsgranska den först).

Felscenarier

  • Name
    400 - Bad Request
    Description

    Begäran kunde inte accepteras. Vanliga orsaker:

    • Saknad parameter: image_url krävs.
    • Ogiltigt bildformat: Den angivna image_url har inte ett format som stöds (.jpg, .jpeg, .png, .webp).
    • Bilddimensioner utanför intervallet: Bilden är för liten, överskrider den maximala filstorleken eller överskrider det maximala antalet pixlar.
    • Onåbar URL: image_url kunde inte laddas ner (404 eller timeout).
    • Ogiltig Data URI: Base64-strängen är felaktigt formaterad.
    • Innehåll flaggat: Den inmatade bilden flaggades av NSFW-moderation.
  • Name
    401 - Unauthorized
    Description

    Autentisering misslyckades. Kontrollera din API-nyckel.

  • Name
    402 - Payment Required
    Description

    Antingen har ditt konto en gratisplan — att skapa uppgifter på denna endpoint kräver en betald plan — eller så har du otillräckligt med credits.

  • Name
    403 - Forbidden
    Description

    Den inmatade bilden flaggades för intrång i immateriella rättigheter.

  • Name
    429 - Too Many Requests
    Description

    Du har överskridit din hastighetsgräns.

Request

POST
/openapi/creative-lab/fidget-collapsible/v1
curl https://api.meshy.cn/openapi/creative-lab/fidget-collapsible/v1 \
  -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>"
  }'

Response

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

GET/openapi/creative-lab/fidget-collapsible/v1/:id

Hämta en Collapsible Fidget-uppgift

Hämta en collapsible fidget-uppgift med hjälp av ett giltigt uppgifts-id. Endast uppgifter som skapats via denna endpoint kan nås här — en uppgift från en annan Creative Lab-endpoint, eller en som skapats i webbappen, returnerar 404.

Se The Collapsible Fidget Task Object för svarets struktur.

Parametrar

  • Name
    id
    Type
    path
    Description

    Unik identifierare för den collapsible fidget-uppgift som ska hämtas.

Returnerar

Svaret innehåller collapsible fidget-uppgiftsobjektet.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.cn/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Ta bort en Collapsible Fidget-uppgift

Avbryt en collapsible fidget-uppgift. Om uppgiften fortfarande är PENDING återbetalas de credits som förbrukades vid skapandet. Uppgifter som redan är IN_PROGRESS avbryts utan återbetalning (arbetaren kan redan hålla på att förbruka resurser). Uppgifter som redan har nått ett slutgiltigt tillstånd (SUCCEEDED, FAILED, CANCELED) kan inte avbrytas.

Sökvägsparametrar

  • Name
    id
    Type
    path
    Description

    Unik identifierare för den collapsible fidget-uppgift som ska avbrytas.

Returnerar

Returnerar 204 No Content vid framgång med en tom body.

Felscenarier

  • Name
    400 - Bad Request
    Description

    Uppgiften befinner sig redan i ett slutgiltigt tillstånd och kan inte avbrytas.

  • Name
    404 - Not Found
    Description

    Uppgiften finns inte, tillhör en annan användare eller skapades inte via denna endpoint.

Request

DELETE
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.cn/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

Streama en Collapsible Fidget-uppgift

Streama realtidsuppdateringar för en collapsible fidget-uppgift via Server-Sent Events (SSE). En uppgift som inte finns, eller som inte skapades via denna endpoint, sänder en enda event: error-payload med status_code: 404 och stänger sedan strömmen.

Parametrar

  • Name
    id
    Type
    path
    Description

    Unik identifierare för den collapsible fidget-uppgift som ska strömmas.

Returnerar

Returnerar en ström av Collapsible Fidget -uppgiftsobjekt som Server-Sent Events. För uppgifter med status PENDING eller IN_PROGRESS kommer svarsströmmen endast att innehålla de nödvändiga fälten progress och status.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.cn/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
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": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

GET/openapi/creative-lab/fidget-collapsible/v1

Lista över hopfällbara fidget-uppgifter

Hämta en paginerad lista över dina hopfällbara fidget-uppgifter. Endast uppgifter som skapats via denna endpoint ingår.

Frågeparametrar

  • Name
    page_num
    Type
    integer
    standard 1
    Description

    Sidnummer för paginering.

  • Name
    page_size
    Type
    integer
    standard 10
    Description

    Gräns för sidstorlek. Maximalt tillåtet är 100 objekt.

  • Name
    sort_by
    Type
    string
    standard -created_at
    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 över objektet för den hopfällbara fidget-uppgiften.

Request

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

Objektet för hopfällbar fidget-uppgift

Objektet för hopfällbar fidget-uppgift är en arbetsenhet som Meshy håller reda på för att omvandla ett källfotografi till en hopfällbar fidget-modell som kan skrivas ut på plats. Det är en uppgift i ett enda steg: det finns ingen prototyp att kedja från, och den mellanliggande silhuetten är inte en del av svaret.

Egenskaper

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Uppgiftens typ. Värdet är creative-lab-fidget-collapsible.

  • Name
    name
    Type
    string
    Description

    Uppgiftsnamnet som angavs när uppgiften skapades. Tom sträng om inget namn angavs.

  • Name
    status
    Type
    string
    Description

    Uppgiftens status. Möjliga värden är ett av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Uppgiftens progress. Om uppgiften ännu inte har startat kommer denna egenskap att vara 0. När uppgiften har lyckats blir den 100.

  • 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 ännu inte har startat kommer denna egenskap att vara null.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tidsstämpel för när uppgiften slutfördes, i millisekunder. Om uppgiften ännu inte har slutförts kommer denna egenskap att vara null.

  • Name
    expires_at
    Type
    timestamp
    Description

    Tidsstämpel för när uppgiftens resultat upphör att gälla, i millisekunder.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Antalet föregående uppgifter.

  • 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 med när uppgiftens status är PENDING, IN_PROGRESS eller SUCCEEDED. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid misslyckande).

  • Name
    model_urls
    Type
    object
    Description

    Nedladdningsbara URL:er för den genererade 3D-modellen. Fylls i när uppgiften har SUCCEEDED: stl finns alltid med, glb endast när förhandsgranskningsrenderingen lyckades.

    • Name
      stl
      Type
      string
      Description

      Nedladdningsbar URL till STL-filen. Detta är den utskrivbara leveransen — skicka den direkt till en slicer.

    • Name
      glb
      Type
      string
      Description

      Nedladdningsbar URL till GLB-filen, för att förhandsgranska modellen i en 3D-visare. Dess färger är endast avsedda för förhandsgranskning: STL bär ingen färg, och en utskriven fidget får sin färg från filamentet. GLB:n tillhandahålls efter bästa förmåga: när förhandsgranskningsrenderingen inte är tillgänglig utelämnas nyckeln helt från model_urls, så läs den defensivt — stl är leveransen och finns alltid med i en SUCCEEDED-uppgift.

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}