Gawing 3D-printable na medalyong keychain ang pinagmulang larawan — isang colorized depth relief na hugis badge — sa dalawang yugto: ang prototype ay bumubuo ng colorized na concept image mula sa iyong input na larawan, pagkatapos ay ginagawang relief 3D model ng build ang concept image na iyon. Magkaugnay ang dalawang yugto sa pamamagitan ng input_task_id.
Bumuo ng iisang colorized concept image mula sa source photo. Ang
ibinalik na task ID ang ipapasa mo bilang input_task_id sa build
endpoint. Sumangguni sa
keychain Prototype Task Object
para sa anyo ng response.
Mga Parameter
Name
image_url
Type
string
Kinakailangan
Description
Source photo na iko-colorize ng Meshy bilang isang concept image na handa para sa keychain. Kasalukuyan naming sinusuportahan ang mga format na .jpg, .jpeg, .png, at .webp.
May dalawang paraan para ibigay ang image:
URL na publicly accessible: Isang URL na maa-access mula sa public internet.
Data URI: Isang base64-encoded Data URI ng image. Halimbawa ng Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
name
Type
string
Description
Opsyonal na pangalan ng task para sa display purposes. Maximum na 100 character.
Mga Ibinabalik
Ang result property ng response ay naglalaman ng task id ng bagong nagawang keychain prototype task. I-poll ang Kumuha ng Task endpoint o mag-subscribe sa stream hanggang umabot ang task sa SUCCEEDED, pagkatapos ay ipasa ang ID na iyon sa build endpoint bilang input_task_id.
Mga Failure Mode
Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Mga karaniwang sanhi:
Nawawalang parameter: Kinakailangan ang image_url.
Invalid na image format: Ang ibinigay na image_url ay hindi suportadong format (.jpg, .jpeg, .png, .webp).
Wala sa saklaw ang dimensions ng image: Masyadong maliit ang image, lumalampas sa maximum file size, o lumalampas sa maximum pixel count.
Hindi maabot na URL: Hindi ma-download ang image_url (404 o timeout).
Invalid na Data URI: Malformed ang base64 string.
Na-flag na content: Na-flag ang input image ng NSFW o intellectual property moderation.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Pakisuri ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat ang credits para isagawa ang task na ito.
Name
429 - Too Many Requests
Description
Lumampas ka sa iyong rate limit.
Request
POST
/openapi/creative-lab/keychain/v1/prototype
# Stage 1: generate a colorized keychain concept imagecurl 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.
Mag-generate ng panghuling 3D-printable na keychain medallion mula sa isang nagtagumpay na
prototype task. Pinapatakbo ng build ang isang depth-map relief pipeline sa
colorized concept image ng prototype at naghahatid ng iisang mesh artifact sa
format na hihingin mo. Sumangguni sa
The Keychain Build Task Object para sa
anyo ng response.
Mga Parameter
Name
input_task_id
Type
string
Kinakailangan
Description
Ang task ID ng isang prototype task na ginawa sa pamamagitan ng parehong OpenAPI endpoint na ito. Dapat nagawa ang prototype gamit ang parehong API key, dapat umabot na sa SUCCEEDED, at dapat nakagawa ng eksaktong isang candidate image.
Ang mga prototype task na ginawa sa pamamagitan ng webapp ay hindi tinatanggap — tinatanggap lamang ng build endpoint ang mga prototype task na ginawa ng POST /openapi/creative-lab/keychain/v1/prototype at tinatanggihan ang anumang ibang source gamit ang 404.
Name
name
Type
string
Description
Opsyonal na pangalan ng task para sa pagpapakita. Maximum na 100 character.
options
Opsyonal na tuning parameters para sa relief geometry. May makatwirang default ang bawat field — ipadala lamang ang mga gusto mong i-override.
Name
badge_shape
Type
string
default circle
Description
Outline silhouette ng keychain medallion. Mga available na value:
circle (default)
rounded-rect
hexagon
shield
star
Name
size_mm
Type
number
default 40
Description
Haba ng gilid ng bounding square ng keychain, sa millimeters. Range: (0, 400].
Name
relief_height_mm
Type
number
default 2.2
Description
Maximum na relief height sa ibabaw ng base, sa millimeters. Range: [0, 20].
Name
relief_offset_mm
Type
number
default 0
Description
Vertical offset na inilalapat sa relief bago ang extrusion, sa millimeters. Range: [0, 20].
Name
base_thickness_mm
Type
number
default 0.1
Description
Kapal ng flat base plate sa likod ng relief, sa millimeters. Range: [0, 20].
Name
has_closed_back
Type
boolean
default true
Description
Kung ang likod ng medallion ay sealed bilang closed surface. Itakda sa false para sa open shell.
Name
relief_curve
Type
string
default linear
Description
Transfer curve na nagmamapa ng depth-map values sa relief height. Mga available na value:
linear (default)
gamma
s-curve
Name
curve_param
Type
number
default 1.0
Description
Shape parameter para sa transfer curve (may kahulugan lamang kapag ang relief_curve ay gamma). Range: (0, 10].
Name
invert_depth
Type
boolean
default false
Description
I-invert ang interpretasyon ng depth-map upang ang mas madidilim na rehiyon ay maging mas mataas na relief.
Name
smoothing
Type
number
default 0.24
Description
Lakas ng smoothing na inilalapat sa depth map bago ang relief extraction. Range: [0, 10].
Name
relief_scale
Type
number
default 1.0
Description
Vertical scale multiplier na inilalapat sa ibabaw ng relief_height_mm. Range: (0, 10].
Name
depth_threshold
Type
number
default 0.1
Description
Low-pass threshold para sa depth-map values; anumang mas mababa rito ay kino-clamp sa zero. Range: [0, 1].
Name
remove_background
Type
boolean
default true
Description
Awtomatikong alisin ang background ng concept image ng prototype bago ang reliefing.
Name
export_resolution
Type
integer
default 512
Description
Mesh resolution na ginagamit para sa export. Range: [64, 2048].
output
Opsyonal na wire-format selector. Default sa glb.
Name
format
Type
string
default glb
Description
Artifact bundle na ibinabalik ng build. Mga available na value:
glb (default) — nagbabalik ng iisang model.glb sa ilalim ng model_urls.glb.
obj — zi-zip ang model.obj + model.mtl + texture.png at ibinabalik ang bundle sa ilalim ng model_urls.obj.
zip — zi-zip ang bawat artifact na inilalabas ng generator at ibinabalik ang bundle sa ilalim ng model_urls.bundle_zip.
Mga Ibinabalik
Ang result property ng response ay naglalaman ng task id ng bagong nagawang keychain build task. I-poll ang Get a Task endpoint o mag-subscribe sa stream hanggang umabot ang task sa SUCCEEDED, pagkatapos ay i-download ang artifact mula sa iisang entry sa model_urls.
Mga Failure Mode
Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Karaniwang sanhi:
Nawawalang parameter: kinakailangan ang input_task_id.
Invalid UUID: Ang input_task_id ay hindi valid na UUID.
Hindi pa nagtagumpay ang parent: Ang nire-reference na prototype task ay hindi pa umaabot sa SUCCEEDED.
Walang candidate: Nagtagumpay ang prototype task ngunit walang nagawang candidate image.
Options out of range: Isa sa mga field ng options ay lumampas sa pinapayagang range o enum set nito.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Pakisuri ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat ang credits para isagawa ang task na ito.
Name
404 - Not Found
Description
Ang nire-reference na prototype task ay hindi umiiral, pagmamay-ari ng ibang user, o ginawa sa pamamagitan ng webapp (tanging API-mode prototype tasks lamang ang maaaring i-chain sa build).
Kunin ang isang prototype o build na gawain gamit ang valid na task id. Ang URL path
ay dapat tumugma sa stage ng gawain — ang build task na kinuha sa pamamagitan ng
/prototype/:id ay nagbabalik ng 404, at ganoon din sa kabaligtaran.
Kanselahin ang isang gawain sa keychain. Kung ang gawain ay PENDING pa rin, ang credits
na nagamit sa oras ng paggawa ay ibinabalik. Ang mga gawaing nasa
IN_PROGRESS na ay kinakansela nang walang refund (maaaring gumagamit na ang worker ng
resources). Ang mga gawaing nakarating na sa terminal na estado
(SUCCEEDED, FAILED, CANCELED) ay hindi maaaring kanselahin.
Dapat tumugma ang URL path sa stage ng gawain — ang DELETE sa
/prototype/:buildId ay nagbabalik ng 404.
Mga Parameter ng Path
Name
id
Type
path
Description
Natatanging identifier para sa gawain sa keychain na kakanselahin.
Mga Ibinabalik
Nagbabalik ng 204 No Content kapag matagumpay, na may walang laman na body.
Mga Mode ng Pagkabigo
Name
400 - Bad Request
Description
Ang gawain ay nasa terminal na estado na at hindi maaaring kanselahin.
Name
404 - Not Found
Description
Ang gawain ay hindi umiiral, pag-aari ng ibang user, o ang stage nito ay hindi tumutugma sa URL path.
Mag-stream ng real-time na mga update para sa isang keychain na gawain sa pamamagitan ng Server-Sent Events (SSE).
Dapat tumugma ang path ng URL sa stage ng gawain — ang pagbubukas ng stream sa
/prototype/:buildId/stream ay naglalabas ng iisang event: error payload na may
status_code: 404 at isinasara ang stream.
Mga Parameter
Name
id
Type
path
Description
Natatanging identifier para sa keychain na gawain na i-stream.
Mga Ibinabalik
Nagbabalik ng stream ng mga object ng gawain na keychain Prototype
o keychain Build bilang
Server-Sent Events. Para sa mga gawaing PENDING o IN_PROGRESS, isasama lang ng response
stream ang kinakailangang mga field na progress at status.
// Error event example (wrong stage or task not found)event: errordata: {"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: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","progress": 0,"status": "PENDING"}event: messagedata: {"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=***" }}
Kunin ang listahang may pagination ng iyong mga gawain sa keychain para sa iisang yugto. Pinipili ng URL
path ang yugto — ibinabalik ng /prototype ang mga prototype task; ibinabalik ng /build
ang mga build task. Hindi kasama sa alinmang
response ang mga task mula sa ibang yugto.
Mga Path Parameter
Name
stage
Type
path
Kinakailangan
Description
Alinman sa prototype o build. Ibinabalik lamang ng koleksiyon ang mga task
na tumutugma ang yugto sa URL — ang pagkuha sa /prototype ay hindi kailanman nagbabalik ng
mga build task at ganoon din sa kabaligtaran.
Mga Query Parameter
Name
page_num
Type
integer
default 1
Description
Numero ng page para sa pagination.
Name
page_size
Type
integer
default 10
Description
Limitasyon sa laki ng page. Ang pinakamataas na pinapayagan ay 50 item.
Name
sort_by
Type
string
default -created_at
Description
Field na pagbabatayan ng pag-uuri. Mga available na value:
+created_at: Pag-uri-uriin ayon sa oras ng paggawa sa pataas na pagkakasunod-sunod.
-created_at: Pag-uri-uriin ayon sa oras ng paggawa sa pababang pagkakasunod-sunod.
Ang object ng Gawaing Prototype ng keychain ay isang yunit ng trabaho na sinusubaybayan ng Meshy upang
bumuo ng may-kulay na larawang konsepto mula sa pinagmulang larawan. Ang output ng
yugtong ito ay ikinakadena sa yugto ng build
sa pamamagitan ng input_task_id.
Mga Katangian
Name
id
Type
string
Description
Natatanging identifier para sa task. Bagama't gumagamit kami ng k-sortable UUID para sa mga task id bilang detalye ng implementasyon, hindi ka dapat gumawa ng anumang palagay tungkol sa format ng id.
Name
type
Type
string
Description
Uri ng task. Ang value ay creative-lab-keychain-prototype.
Name
name
Type
string
Description
Ang pangalan ng task na ibinigay noong ginawa ang task. Empty string kung walang ibinigay na pangalan.
Name
status
Type
string
Description
Status ng task. Ang mga posibleng value ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress ng task. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0. Kapag nagtagumpay na ang task, magiging 100 ito.
Name
created_at
Type
timestamp
Description
timestamp kung kailan ginawa ang task, sa milliseconds.
Ang timestamp ay kumakatawan sa bilang ng milliseconds na lumipas mula Enero 1, 1970 UTC, alinsunod sa
pamantayang RFC 3339.
Halimbawa, ang Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Nalalapat ito
sa lahat ng timestamp sa Meshy API.
Name
started_at
Type
timestamp
Description
timestamp kung kailan sinimulan ang task, sa milliseconds. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0.
Name
finished_at
Type
timestamp
Description
timestamp kung kailan natapos ang task, sa milliseconds. Kung hindi pa natatapos ang task, ang property na ito ay magiging 0.
Name
expires_at
Type
timestamp
Description
timestamp kung kailan mag-e-expire ang resulta ng task, sa milliseconds.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga naunang task.
Makabuluhan lamang ang value ng field na ito kung ang status ng task ay PENDING.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa buong reference ng object na task_error.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na nagamit ng task na ito. Naroroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga task na FAILED (nire-refund ang credits kapag nabigo).
Name
image_urls
Type
array of strings
Description
Mga nada-download na URL para sa mga candidate na concept image na nabuo ng prototype task na ito. Sa kasalukuyan, laging nagbabalik ang API ng eksaktong isang candidate; ang field ay array upang sa mga susunod na rebisyon ay maipakita ang maraming candidate nang walang breaking change.
Ang keychain Build Task object ay isang work unit na sinusubaybayan ng Meshy upang
bumuo ng panghuling 3D keychain mesh mula sa isang matagumpay na prototype task. Ang
build ay nagpapatakbo ng depth-map relief pipeline sa concept image ng prototype at
nagpa-publish ng iisang mesh artifact sa format na hiniling ng tumatawag.
Mga Property
Name
id
Type
string
Description
Natatanging identifier para sa task.
Name
type
Type
string
Description
Uri ng task. Ang value ay creative-lab-keychain-build.
Name
name
Type
string
Description
Ang pangalan ng task na ibinigay noong ginawa ang task. Empty string kung walang ibinigay na pangalan.
Name
status
Type
string
Description
Status ng task. Ang mga posibleng value ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress ng task. Kung hindi pa nasisimulan ang task, ang property na ito ay magiging 0. Kapag nagtagumpay na ang task, magiging 100 ito.
Name
created_at
Type
timestamp
Description
Timestamp kung kailan ginawa ang task, sa milliseconds.
Name
started_at
Type
timestamp
Description
Timestamp kung kailan sinimulan ang task, sa milliseconds.
Name
finished_at
Type
timestamp
Description
Timestamp kung kailan natapos ang task, sa milliseconds.
Name
expires_at
Type
timestamp
Description
Timestamp kung kailan mag-e-expire ang resulta ng task, sa milliseconds.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga naunang task. May kahulugan lamang kapag ang status ay PENDING.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa buong reference ng object na task_error.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na nakonsumo ng task na ito. Nagbabalik ng 0 para sa mga FAILED na task (ibinabalik ang credits kapag nabigo).
Name
model_urls
Type
object
Description
Mga nada-download na URL para sa nabuong artifact, naka-key ayon sa pangalan ng artifact. Palaging naglalaman ng eksaktong isang entry — ang format na hiniling sa pamamagitan ng build request na output.format. Tumutugma ang key sa hiniling na format:
Name
glb
Type
string
Description
Nada-download na URL papunta sa GLB file. Naroroon kapag ang output.format ay glb (ang default).
Name
obj
Type
string
Description
Nada-download na URL papunta sa zip bundle na naglalaman ng model.obj, model.mtl, at texture.png. Naroroon kapag ang output.format ay obj.
Name
bundle_zip
Type
string
Description
Nada-download na URL papunta sa zip bundle ng bawat artifact na inilalabas ng generator. Naroroon kapag ang output.format ay zip.