Creative Lab Collapsible Fidget API

Förvandla ett foto till en hopfällbar fidget-leksak som skrivs ut på plats i en enda uppgift. Motivets silhuett blir till koncentriska ringar som kan fällas ihop platt och sträckas ut igen. Leksaken skrivs ut 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 ingen separat prototyp- och byggfas. Det finns inga kandidatbilder att välja mellan, så en enda uppgift förvandlar fotot till en 3D-modell.

Begäran har inte heller några geometriinställningar. Webbappen låter dig ställa in storlek, antal lager, gapbredd, väggtjocklek, extruderingsdjup och utbuktning. Varje API-uppgift använder samma standardvärden för dessa.

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

Skapa en Collapsible Fidget-uppgift

Genererar en hopfällbar fidget-modell från ett foto. För uppgiftens fält, se The Collapsible Fidget task object.

Varje uppgift kostar 6 credits och kräver en betalplan.

Request

POST

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

curl https://api.meshy.ai/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"
}

Parametrar

Name
image_url
Type
string
Obligatorisk
Description
Fotot som ska omvandlas till en hopfällbar fidget, antingen som en offentlig URL eller en data-URI (data:image/jpeg;base64,<dina base64-kodade bilddata>).
Bilden måste vara en JPG-, JPEG-, PNG- eller WebP-fil på högst 20 MB.
Motivets siluett blir ringarna, så ett motiv med en tydlig, sluten kontur fungerar bäst. En rörig bakgrund, flera separata motiv eller mycket tunna former kan lämna för lite yta för de nästlade väggarna. I så fall misslyckas uppgiften.
Name
name
Type
string
Description
Ett namn för uppgiften, upp till 100 tecken. Det kommer tillbaka i uppgiftens name-fält, och Meshy graverar det inte på modellen. Ett längre namn returnerar 400.

Returnerar

Fältet result innehåller ID:t för den nya uppgiften. Hämta uppgiften eller strömma den tills status är SUCCEEDED. Ladda sedan ner den utskrivbara STL-filen från model_urls.stl. För att förhandsgranska modellen först, ladda ner GLB-filen från model_urls.glb när den finns.

Felscenarier

Name
400 - Bad Request
Description
Begäran kan inte köras. Till exempel:
- image_url saknas.
- Bilden är inte en JPG-, JPEG-, PNG- eller WebP-fil.
- Bilden är för liten, över 20 MB, eller över det maximala antalet pixlar.
- Meshy kan inte ladda ner bilden, till exempel för att URL:en returnerar 404 eller tidsgränsen löper ut.
- Data-URI:n är inte giltig base64.
- Bilden flaggades som olämplig (NSFW).
Felmeddelandet anger vilket problem som hittades. Åtgärda begäran och skicka den igen.
Name
401 - Unauthorized
Description
API-nyckeln saknas eller är ogiltig. Kontrollera Authorization-headern.
Name
402 - Payment Required
Description
Något av följande gäller:
- Kontot har inte tillräckligt med credits.
- API-nyckeln, arbetsytan eller medlemmen har nått sin creditgräns.
- Kontot har en gratisplan.
Kontrollera dina credits och din plan, och försök sedan igen.
Name
403 - Forbidden
Description
Ditt team har IP Filtering aktiverat, och Meshy har flaggat bilden för tredje parts immateriella rättigheter. Skicka en bild som du har rätt att använda.
Name
429 - Too Many Requests
Description
En av följande gränser har nåtts:
- Du har skickat fler förfrågningar än vad din hastighetsgräns tillåter. Vänta några sekunder och försök sedan igen. Se Rate limits.
- För många av dina uppgifter är köade eller pågår. Vänta tills några är klara och försök sedan igen.
- På en obegränsad plan utan kvarvarande credits har du nått antalet uppgifter som kan köras utan credits. Vänta tills en uppgift är klar, eller lägg till credits.
Name
500 - Internal Server Error
Description
Meshy stötte på ett serverfel, till exempel för att det inte gick att köra kontrollen av immateriella rättigheter på bilden. Meshy skapar inte uppgiften och återbetalar eventuella credits som debiterats. Försök igen med begäran.

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

Hämta en Collapsible Fidget-uppgift

Returnerar en Collapsible Fidget-uppgift. Endast uppgifter som skapats med denna endpoint returneras. En uppgift från en annan Creative Lab-endpoint, eller en som skapats i webbappen, returnerar 404.

För fälten, se The Collapsible Fidget task object.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/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.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

Parametrar

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

Returnerar

Collapsible Fidget task object.

Felscenarier

Name
400 - Bad Request
Description
id är inte ett giltigt uppgifts-ID. Skicka result-ID:t från skapandesvaret.
Name
403 - Forbidden
Description
Ditt team har IP Filtering aktiverat, och Meshy flaggade uppgiftens bild för immateriell egendom som tillhör tredje part. Team med Enterprise-planen får inte detta fel. Skapa en uppgift från en bild som du har rättigheter att använda.
Name
404 - Not Found
Description
Ingen Collapsible Fidget-uppgift med detta ID tillhör ditt konto, eller så skapades inte uppgiften med denna endpoint. Kontrollera ID:t.
Name
500 - Internal Server Error
Description
Meshy kunde inte köra kontrollen av immateriell egendom. Försök igen med förfrågan.

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

Ta bort en Collapsible Fidget-uppgift

Avbryter en Collapsible Fidget-uppgift. Att avbryta en PENDING-uppgift återbetalar dess credits. En IN_PROGRESS-uppgift avbryts utan återbetalning, eftersom en arbetare redan har påbörjat den. En uppgift med en slutgiltig status (SUCCEEDED, FAILED eller CANCELED) kan inte avbrytas.

Request

DELETE

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/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).

Sökvägsparametrar

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

Returnerar

204 No Content med en tom body.

Felscenarion

Name
400 - Bad Request
Description
Något av följande gäller:
- id är inte ett giltigt uppgifts-ID. Skicka result-ID:t från svaret vid skapandet.
- Uppgiften har redan en slutgiltig status (SUCCEEDED, FAILED eller CANCELED), så den kan inte avbrytas.
Name
404 - Not Found
Description
Ingen Collapsible Fidget-uppgift med detta ID tillhör ditt konto, eller så skapades uppgiften inte med denna endpoint. Kontrollera ID:t.

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

Strömma en Collapsible Fidget-uppgift

Strömmar uppdateringar för en Collapsible Fidget-uppgift som Server-Sent Events (SSE). Om uppgiften inte finns eller inte skapades med denna endpoint skickar strömmen en error-händelse med status_code: 404 och stängs.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/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.
// Every frame is the full task object; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
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.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

Parametrar

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

Returnerar

En ström av Collapsible Fidget-uppgiftsobjekt. Varje händelse innehåller det fullständiga uppgiftsobjektet, så som Hämta en Collapsible Fidget-uppgift returnerar det. Medan uppgiften är PENDING eller IN_PROGRESS är dess utdatafält fortfarande tomma (null, [] eller {}), och finished_at är null.

Om IP Filtering blockerar uppgiftens resultat skickar strömmen istället en error-händelse, med den status_code som en get-förfrågan skulle returnera.

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

Lista Collapsible Fidget-uppgifter

Returnerar dina Collapsible Fidget-uppgifter, en sida i taget. Endast uppgifter skapade med denna endpoint ingår.

Request

GET

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

curl https://api.meshy.ai/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.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

Frågeparametrar

Name
page_num
Type
integer
standard 1
Description
Sidan som ska returneras, från 1 till 255. 0 returnerar den första sidan. Ett värde utanför 0 till 255 returnerar 400.
Name
page_size
Type
integer
standard 10
Description
Antal uppgifter per sida, upp till 100. Ett värde från 101 till 255 returnerar 100 uppgifter, och 0 använder standardvärdet. Ett värde utanför 0 till 255 returnerar 400.
Name
sort_by
Type
string
standard -created_at
Description
Sorteringsordningen.
Tillgängliga värden:
- -created_at: nyaste först
- +created_at: äldsta först

Returnerar

En array av Collapsible Fidget-uppgiftsobjekt.

Det hopfällbara fidget-task-objektet

En Collapsible Fidget-task omvandlar ett foto till en print-in-place hopfällbar fidget-modell. Det är en engångs-task, så det finns ingen prototyp-task att länka från. Svaret innehåller inte silhuetten som Meshy skapar på vägen.

Egenskaper

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.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

Name
id
Type
string
Description
Task-ID:t. Lita inte på dess format.
Name
type
Type
string
Description
Task-typen, alltid creative-lab-fidget-collapsible.
Name
name
Type
string
Description
name du skickade när du skapade task:en, eller "" om du inte skickade någon.
Name
status
Type
string
Description
Task:ens status.
Tillgängliga värden:
- PENDING: väntar i kön
- IN_PROGRESS: genererar resultatet
- SUCCEEDED: slutgiltigt, med resultatet
- FAILED: slutgiltigt, med orsaken i task_error
- CANCELED: slutgiltigt, utan resultat
Name
progress
Type
integer
Description
Procent av arbetet som är klart, från 0 till 100. Det är 0 tills task:en startar och 100 när den lyckas.
Name
created_at
Type
timestamp
Description
Tidpunkt då task:en skapades, i Unix-millisekunder.
Name
started_at
Type
timestamp
Description
Tidpunkt då en arbetare startade task:en, i Unix-millisekunder. null fram till dess.
Name
finished_at
Type
timestamp
Description
Tidpunkt då task:en nådde en slutgiltig status, i Unix-millisekunder. null fram till dess.
Name
expires_at
Type
timestamp
Description
Tidpunkt då task:ens resultat upphör att gälla, i Unix-millisekunder. Det är 3 dagar efter finished_at, eller 3 dagar efter created_at tills task:en är klar. För Enterprise-konton, som behåller API-resultat på obestämd tid, är det ungefär 100 år senare. Se Tillgångslagring.
Name
preceding_tasks
Type
integer
Description
Task:ens position i kön medan den är PENDING. 1 betyder att den startar härnäst. 0 efter att task:en lämnat kön, och alltid 0 i listresultat.
Name
task_error
Type
object
Description
Varför task:en misslyckades. null om inte status är FAILED. Se Fel.
Name
consumed_credits
Type
integer
Description
Antal credits som debiterats för task:en, efter eventuell återbetalning. En begäran som returnerar ett fel debiteras inte. En misslyckad task är 0, eftersom Meshy återbetalar den. Att avbryta återbetalar en task endast medan den är PENDING. Om Meshy inte kan läsa debiteringen utelämnar ett get- eller stream-svar fältet, och en listbegäran returnerar 500. I så fall, försök igen med begäran.
Name
model_urls
Type
object
Description
Nedladdnings-URL:er för 3D-modellen, tomma tills task:en lyckas. En lyckad task har alltid stl, och har glb endast om Meshy renderade förhandsvisningen.
- Name
  stl
  Type
  string
  Description
  Nedladdnings-URL för STL-filen, som är filen att skriva ut. Du kan öppna den direkt i en slicer.
- Name
  glb
  Type
  string
  Description
  Nedladdnings-URL för en GLB-fil för att förhandsgranska modellen i en 3D-visare. Dess färger är endast för förhandsvisningen. STL-filen har ingen färg, så den utskrivna fidget-leksaken får sin färg från filamentet.
  Om Meshy inte kan rendera förhandsvisningen saknar model_urls nyckeln glb, så kontrollera om nyckeln finns innan du läser den. En SUCCEEDED-task har alltid stl.