Creative Lab — nyckelring API

Förvandla ett källfoto till en 3D-utskrivbar nyckelringsmedaljong — en märkesformad färglagd djuprelief — i två steg: prototype genererar en färglagd konceptbild från ditt inmatningsfoto, sedan omvandlar build den konceptbilden till en 3D-reliefmodell. De två stegen är länkade via input_task_id.

POST /openapi/creative-lab/keychain/v1/prototype
POST /openapi/creative-lab/keychain/v1/build

POST/openapi/creative-lab/keychain/v1/prototype

Skapa en prototypuppgift för nyckelring

Generera en enda färglagd konceptbild från källfotot. Det returnerade uppgifts-ID:t är det du skickar som input_task_id till build- endpointen. Se Objektet Keychain Prototype Task för svarsformatet.

Parametrar

Name
image_url
Type
string
Obligatorisk
Description
Källfoto som Meshy ska färglägga till en konceptbild redo för nyckelring. Vi stöder för närvarande formaten .jpg, .jpeg, .png och .webp.
Det finns två sätt att ange bilden:
- Publikt åtkomlig URL: En URL som är åtkomlig från det publika internet.
- Data URI: En base64-kodad Data URI för bilden. Exempel på en Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
name
Type
string
Description
Valfritt uppgiftsnamn för visningsändamål. Högst 100 tecken.

Returnerar

Egenskapen result i svaret innehåller uppgiftens id för den nyligen skapade prototypuppgiften för nyckelring. Polla endpointen Hämta en uppgift eller prenumerera på streamen tills uppgiften når SUCCEEDED, skicka sedan det ID:t till build-endpointen som input_task_id.

Fellägen

Name
400 - Bad Request
Description
Begäran var inte acceptabel. 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 pixelantalet.
- Oåtkomlig URL: image_url kunde inte hämtas (404 eller timeout).
- Ogiltig Data URI: Base64-strängen är felaktigt formaterad.
- Flaggat innehåll: Indatabilden flaggades av NSFW- eller immaterialrätts-moderation.
Name
401 - Unauthorized
Description
Autentisering misslyckades. Kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckligt med credits för att utföra den här uppgiften.
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.

Request

POST

/openapi/creative-lab/keychain/v1/prototype

# Stage 1: generate a colorized keychain concept image
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype \
  -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"
}

Prototype example

Start with a source photo, then generate the prototype image used by the keychain build stage.

Källfoto som används som indata för Creative Lab Keychain — Prototype input

Creative Lab Keychain-prototyputdata genererade från källfotot — Prototype output

POST/openapi/creative-lab/keychain/v1/build

Skapa en bygguppgift för nyckelring

Generera den slutliga 3D-utskrivbara nyckelringsmedaljongen från en lyckad prototypuppgift. Bygget kör en reliefpipeline med djupkarta på prototypens färglagda konceptbild och levererar en enda nät-artefakt i formatet du begär. Se Objektet Keychain Build Task för svarstrukturen.

Parametrar

Name
input_task_id
Type
string
Obligatorisk
Description
Uppgifts-ID:t för en prototypuppgift som skapats via samma OpenAPI-endpoint. Prototypen måste ha skapats med samma API-nyckel, måste ha nått SUCCEEDED och måste ha producerat exakt en kandidatbild.
Prototypuppgifter som skapats via webbappen accepteras inte — bygg-endpoint accepterar endast prototypuppgifter som producerats av POST /openapi/creative-lab/keychain/v1/prototype och avvisar alla andra källor med 404.
Name
name
Type
string
Description
Valfritt uppgiftsnamn för visningsändamål. Högst 100 tecken.

`options`

Valfria justeringsparametrar för reliefgeometrin. Varje fält har ett rimligt standardvärde — skicka endast de du vill åsidosätta.

Name
badge_shape
Type
string
standard circle
Description
Kontursilhuett för nyckelringsmedaljongen. Tillgängliga värden:
- circle (standard)
- rounded-rect
- hexagon
- shield
- star
Name
size_mm
Type
number
standard 40
Description
Kantlängd för nyckelringens omslutande kvadrat, i millimeter. Intervall: (0, 400].
Name
relief_height_mm
Type
number
standard 2.2
Description
Maximal reliefhöjd ovanför basen, i millimeter. Intervall: [0, 20].
Name
relief_offset_mm
Type
number
standard 0
Description
Vertikal förskjutning som tillämpas på reliefen före extrudering, i millimeter. Intervall: [0, 20].
Name
base_thickness_mm
Type
number
standard 0.1
Description
Tjocklek på den platta basplattan bakom reliefen, i millimeter. Intervall: [0, 20].
Name
has_closed_back
Type
boolean
standard true
Description
Om medaljongens baksida är förseglad som en sluten yta. Sätt till false för ett öppet skal.
Name
relief_curve
Type
string
standard linear
Description
Överföringskurva som mappar djupkartans värden till reliefhöjd. Tillgängliga värden:
- linear (standard)
- gamma
- s-curve
Name
curve_param
Type
number
standard 1.0
Description
Formparameter för överföringskurvan (endast meningsfull när relief_curve är gamma). Intervall: (0, 10].
Name
invert_depth
Type
boolean
standard false
Description
Invertera tolkningen av djupkartan så att mörkare områden blir högre relief.
Name
smoothing
Type
number
standard 0.24
Description
Utjämningsstyrka som tillämpas på djupkartan innan reliefen extraheras. Intervall: [0, 10].
Name
relief_scale
Type
number
standard 1.0
Description
Vertikal skalmultiplikator som tillämpas ovanpå relief_height_mm. Intervall: (0, 10].
Name
depth_threshold
Type
number
standard 0.1
Description
Lågpasströskel för djupkartans värden; allt under detta kläms till noll. Intervall: [0, 1].
Name
remove_background
Type
boolean
standard true
Description
Ta automatiskt bort bakgrunden från prototypens konceptbild innan reliefen skapas.
Name
export_resolution
Type
integer
standard 512
Description
Nät (mesh)-upplösning som används för export. Intervall: [64, 2048].

`output`

Valfri väljare för överföringsformat. Standardvärdet är glb.

Name
format
Type
string
standard glb
Description
Artefaktpaket som returneras av bygget. Tillgängliga värden:
- glb (standard) — returnerar en enda model.glb under model_urls.glb.
- obj — zippar model.obj + model.mtl + texture.png och returnerar paketet under model_urls.obj.
- zip — zippar varje artefakt som generatorn avger och returnerar paketet under model_urls.bundle_zip.

Returnerar

Egenskapen result i svaret innehåller uppgiftens id för den nyligen skapade bygguppgiften för nyckelring. Polla endpoint Hämta en uppgift eller prenumerera på strömmen tills uppgiften når SUCCEEDED, ladda sedan ner artefakten från den enda posten i model_urls.

Fellägen

Name
400 - Bad Request
Description
Begäran var inte acceptabel. Vanliga orsaker:
- Parameter saknas: input_task_id krävs.
- Ogiltig UUID: input_task_id är inte en giltig UUID.
- Överordnad inte lyckad: Den refererade prototypuppgiften har inte nått SUCCEEDED ännu.
- Ingen kandidat: Prototypuppgiften lyckades men producerade ingen kandidatbild.
- Alternativ utanför intervallet: Ett av fälten i options låg utanför sitt tillåtna intervall eller sin enum-uppsättning.
Name
401 - Unauthorized
Description
Autentisering 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
Den refererade prototypuppgiften finns inte, tillhör en annan användare eller skapades via webbappen (endast prototypuppgifter i API-mode kan kedjas till bygge).
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.

Request

POST

/openapi/creative-lab/keychain/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "badge_shape": "circle",
      "size_mm": 40,
      "relief_height_mm": 2.5
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

Byggexempel

Bygguppgiften konverterar den valda prototypbilden till en 3D-utskrivbar nyckelringsmodell.

Creative Lab förhandsvisning av byggmodell för nyckelring — Förhandsvisning av byggmodell

GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Hämta en nyckelringsuppgift

Hämta en prototyp- eller bygguppgift med ett giltigt uppgifts-id. URL-sökvägen måste matcha uppgiftens fas — en bygguppgift som hämtas via /prototype/:id returnerar 404, och tvärtom.

Se Objektet för nyckelringsprototypuppgift och Objektet för nyckelringsbygguppgift för svarsformat.

Parametrar

Name
id
Type
path
Description
Unik identifierare för nyckelringsuppgiften som ska hämtas.

Returnerar

Svaret innehåller objektet för nyckelringsuppgiften. Formatet beror på vilken fas som begärdes.

Request

GET

/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

DELETE/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Ta bort en nyckelringsuppgift

Avbryt en nyckelringsuppgift. 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 terminalt tillstånd (SUCCEEDED, FAILED, CANCELED) kan inte avbrytas.

URL-sökvägen måste matcha uppgiftens steg — DELETE på /prototype/:buildId returnerar 404.

Sökvägsparametrar

Name
id
Type
path
Description
Unik identifierare för nyckelringsuppgiften som ska avbrytas.

Returnerar

Returnerar 204 No Content vid lyckat resultat med en tom body.

Fellägen

Name
400 - Bad Request
Description
Uppgiften är redan i ett terminalt tillstånd och kan inte avbrytas.
Name
404 - Not Found
Description
Uppgiften finns inte, tillhör en annan användare eller dess steg matchar inte URL-sökvägen.

Request

DELETE

/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

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

GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id/stream

Strömma en nyckelringsuppgift

Strömma uppdateringar i realtid för en nyckelringsuppgift via Server-Sent Events (SSE). URL-sökvägen måste matcha uppgiftens steg — att öppna en ström vid /prototype/:buildId/stream skickar en enda event: error payload med status_code: 404 och stänger strömmen.

Parametrar

Name
id
Type
path
Description
Unik identifierare för nyckelringsuppgiften som ska strömmas.

Returnerar

Returnerar en ström av uppgiftsobjekt för nyckelringsprototyp eller nyckelringsbygge som Server-Sent Events. För PENDING- eller IN_PROGRESS-uppgifter kommer svarsströmmen endast att inkludera de nödvändiga fälten progress och status.

Request

GET

/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
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": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

GET/openapi/creative-lab/keychain/v1/(prototype|build)

Lista nyckelringsuppgifter

Hämta en paginerad lista över dina nyckelringsuppgifter för ett enskilt steg. URL- sökvägen väljer steget — /prototype returnerar prototypuppgifter; /build returnerar bygguppgifter. Uppgifter från det andra steget inkluderas inte i något svar.

Sökvägsparametrar

Name
stage
Type
path
Obligatorisk
Description
Antingen prototype eller build. Samlingen returnerar endast uppgifter vars steg matchar URL:en — hämtning av /prototype returnerar aldrig bygguppgifter och vice versa.

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. Högsta tillåtna är 50 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 uppgiftsobjektet per steg — antingen nyckelringens prototypuppgiftsobjekt vid listning av /prototype eller nyckelringens bygguppgiftsobjekt vid listning av /build.

Request

GET

/openapi/creative-lab/keychain/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-keychain-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

Nyckelringens prototypuppgiftsobjekt

Nyckelringens prototypuppgiftsobjekt är en arbetsenhet som Meshy håller reda på för att generera en färglagd konceptbild från ett källfoto. Utdata från detta steg kopplas vidare till byggsteget via input_task_id.

Egenskaper

Name
id
Type
string
Description
Unik identifierare för uppgiften. Även om vi använder ett k-sorterbart UUID för uppgifts-id:n som implementeringsdetalj, bör du inte göra några antaganden om id:t format.
Name
type
Type
string
Description
Typ av uppgift. Värdet är creative-lab-keychain-prototype.
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 inte har startats ännu är denna egenskap 0. När uppgiften har slutförts framgångsrikt blir detta 100.
Name
created_at
Type
timestamp
Description
Tidsstämpel för när uppgiften skapades, i millisekunder.
En tidsstämpel representerar antalet millisekunder som har förflutit sedan 1 januari 1970 UTC, enligt standarden RFC 3339. Till exempel representeras fredag 1 september 2023 12:00:00 GMT som 1693569600000. Detta gäller alla tidsstämplar i Meshy API.
Name
started_at
Type
timestamp
Description
Tidsstämpel för när uppgiften startades, i millisekunder. Om uppgiften inte har startats ännu är denna egenskap 0.
Name
finished_at
Type
timestamp
Description
Tidsstämpel för när uppgiften slutfördes, i millisekunder. Om uppgiften inte är slutförd ännu är denna egenskap 0.
Name
expires_at
Type
timestamp
Description
Tidsstämpel för när uppgiftsresultatet löper ut, i millisekunder.
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter.
Värdet för detta fält är endast meningsfullt om uppgiftens status är PENDING.
Name
task_error
Type
object
Description
Feldetaljer för misslyckade uppgifter. Se Fel för den fullständiga objektreferensen för task_error.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av denna uppgift. Finns när uppgiftens status är PENDING, IN_PROGRESS eller SUCCEEDED. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid fel).
Name
image_urls
Type
array of strings
Description
Nedladdningsbara URL:er för konceptbildskandidaterna som genereras av denna prototypuppgift. För närvarande returnerar API:t alltid exakt en kandidat; fältet är en array så att framtida versioner kan visa flera kandidater utan en brytande ändring.

Example Keychain Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

The Keychain Build Task Object

Objektet för bygguppgift för nyckelring är en arbetsenhet som Meshy håller reda på för att generera det slutliga 3D-nätet (mesh) för nyckelringen från en SUCCEEDED prototypuppgift. Bygget kör en relief-pipeline med djupkarta på prototypens konceptbild och publicerar en enda nätartefakt (mesh) i det format som anroparen begärde.

Egenskaper

Name
id
Type
string
Description
Unik identifierare för uppgiften.
Name
type
Type
string
Description
Typ av uppgift. Värdet är creative-lab-keychain-build.
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 inte har startats ännu kommer denna egenskap att vara 0. När uppgiften har lyckats blir detta 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.
Name
finished_at
Type
timestamp
Description
Tidsstämpel för när uppgiften slutfördes, i millisekunder.
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. Meningsfullt endast när status är PENDING.
Name
task_error
Type
object
Description
Feldetaljer för misslyckade uppgifter. Se Fel för den fullständiga objektreferensen för task_error.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av denna uppgift. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid fel).
Name
model_urls
Type
object
Description
Nedladdningsbara URL:er för den genererade artefakten, nycklade efter artefaktnamn. Innehåller alltid exakt en post — formatet som begärdes via byggbegärans output.format. Nyckeln matchar det begärda formatet:
- Name
  glb
  Type
  string
  Description
  Nedladdningsbar URL till GLB-filen. Finns när output.format var glb (standardvärdet).
- Name
  obj
  Type
  string
  Description
  Nedladdningsbar URL till ett zip-paket som innehåller model.obj, model.mtl och texture.png. Finns när output.format var obj.
- Name
  bundle_zip
  Type
  string
  Description
  Nedladdningsbar URL till ett zip-paket med varje artefakt som generatorn skapar. Finns när output.format var zip.

Example Keychain Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}