{"openapi":"3.1.0","info":{"title":"3D Valley API","version":"1.0.0","summary":"A free CC0 library of 3D models, textures and HDRIs, and 3D generation and editing for credits.","description":"Docs: https://3dvalley.com/docs/api. MCP server: https://3dvalley.com/mcp.","contact":{"email":"hello@3dvalley.com","url":"https://3dvalley.com/docs/api"}},"servers":[{"url":"https://3dvalley.com/api/v1"}],"security":[{"bearer":[]},{}],"paths":{"/assets":{"get":{"operationId":"searchAssets","summary":"Search the CC0 library","security":[{"bearer":[]},{}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Words, searched by meaning and keyword."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["model","texture","hdri"]},"description":"Asset type."},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"A category slug (GET /categories)."},{"name":"style","in":"query","required":false,"schema":{"type":"string","enum":["realistic","stylized","lowpoly","scan"]},"description":"Style."},{"name":"max_tris","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"At most this many triangles."},{"name":"min_tris","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"At least this many triangles."},{"name":"min_size_m","in":"query","required":false,"schema":{"type":"number","minimum":0},"description":"Largest side at least this many metres."},{"name":"max_size_m","in":"query","required":false,"schema":{"type":"number","minimum":0},"description":"Largest side at most this many metres."},{"name":"maps","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated maps the asset must all have."},{"name":"min_res","in":"query","required":false,"schema":{"type":"string"},"description":"Smallest texture resolution: 1k, 2k, 4k."},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["glb","gltf","obj","stl","zip","hdr","exr","png","jpg"]},"description":"A format we serve it in."},{"name":"rigged","in":"query","required":false,"schema":{"type":"boolean"},"description":"Rigged or not."},{"name":"animated","in":"query","required":false,"schema":{"type":"boolean"},"description":"Animated or not."},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["polyhaven","ambientcg","kenney","kaykit","openhdri","cgbookcase","texturecan"]},"description":"Where it comes from."},{"name":"pack","in":"query","required":false,"schema":{"type":"string"},"description":"A pack id (\"kn:mini-skate\") from a result: every asset of that kit, so a game keeps one style."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["relevance","popular","newest"],"default":"relevance"},"description":"Order."},{"name":"similar_to","in":"query","required":false,"schema":{"type":"string"},"description":"An asset id: the nearest by meaning."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Page size."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"next_cursor of the previous page."},{"name":"detail","in":"query","required":false,"schema":{"type":"string","enum":["concise","full"],"default":"concise"},"description":"How much of each asset."}],"responses":{"200":{"description":"Matching assets","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"]}}}}}},"400":{"description":"invalid_param","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets/{id}":{"get":{"operationId":"getAsset","summary":"One asset with its files, scale, credit line and import notes","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"ph:wooden_barrel_01"}],"responses":{"200":{"description":"The asset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets/{id}/download":{"get":{"operationId":"downloadAsset","summary":"Redirect to a file on the CDN","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Asset id"},{"name":"format","in":"query","schema":{"type":"string"}},{"name":"res","in":"query","schema":{"type":"string"}},{"name":"map","in":"query","schema":{"type":"string"}}],"responses":{"302":{"description":"Location: the file"},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets/{id}/preview":{"get":{"operationId":"assetPreview","summary":"Redirect to the preview picture","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Asset id"},{"name":"size","in":"query","schema":{"type":"string","enum":["256","512","1024"]}}],"responses":{"302":{"description":"Location: the picture"}}}},"/categories":{"get":{"operationId":"listCategories","summary":"Categories with counts","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["model","texture","hdri"]}}],"responses":{"200":{"description":"Categories"}}}},"/tools":{"get":{"operationId":"listTools","summary":"Every tool with its models, prices, inputs, options and limits","responses":{"200":{"description":"The price list"}}}},"/jobs":{"post":{"operationId":"createJob","summary":"Start a job","security":[{"bearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255}},{"name":"Prefer","in":"header","required":false,"schema":{"type":"string","example":"wait=50"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobRequest"}}}},"responses":{"200":{"description":"The same job again (same Idempotency-Key and body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"201":{"description":"Created and finished within the wait","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"202":{"description":"Created, still running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"invalid_param","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"input_rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"spend_cap_reached, rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listJobs","summary":"Your jobs, newest first","security":[{"bearer":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"tool","in":"query","schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Jobs","content":{"application/json":{"schema":{"type":"object","properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/Job"}},"next_cursor":{"type":["string","null"]}}}}}}}}},"/jobs/{id}":{"get":{"operationId":"getJob","summary":"A job as it stands; Prefer: wait=N waits for it","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"job_..."},{"name":"Prefer","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"The job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{id}/events":{"get":{"operationId":"jobEvents","summary":"Server-sent events: progress, then done","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"job_..."}],"responses":{"200":{"description":"text/event-stream"}}}},"/jobs/{id}/cancel":{"post":{"operationId":"cancelJob","summary":"Cancel a job that has not started","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"job_..."}],"responses":{"200":{"description":"The job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"409":{"description":"conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/uploads":{"post":{"operationId":"createUpload","summary":"Get a URL to PUT a file to","security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename","bytes"],"additionalProperties":false,"properties":{"filename":{"type":"string"},"bytes":{"type":"integer"},"content_type":{"type":"string"}}}}}},"responses":{"201":{"description":"The upload with its put_url and a curl command"}}}},"/account":{"get":{"operationId":"getAccount","summary":"Balance, tier, limits, this key's cap, prices","security":[{"bearer":[]}],"responses":{"200":{"description":"The account"}}}},"/account/usage":{"get":{"operationId":"getUsage","summary":"Credits and jobs per day","security":[{"bearer":[]}],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90}}],"responses":{"200":{"description":"Usage"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key (3dv_live_...) or an OAuth access token."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","docs"],"properties":{"code":{"type":"string","enum":["unauthorized","insufficient_scope","not_found","invalid_param","insufficient_credits","spend_cap_reached","rate_limited","idempotency_conflict","input_rejected","provider_failed","conflict","unavailable"]},"message":{"type":"string"},"fix":{"type":"string"},"docs":{"type":"string"}}}}},"Asset":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"category":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"license":{"type":"string"},"size_m":{"type":["array","null"],"items":{"type":"number"}},"tris":{"type":["integer","null"]},"maps":{"type":"array","items":{"type":"string"}},"max_res":{"type":["string","null"]},"preview":{"type":"string"},"download":{"type":["string","null"]}}},"JobRequest":{"type":"object","required":["tool","input"],"additionalProperties":false,"properties":{"tool":{"type":"string","enum":["image-to-3d","text-to-3d","retexture","remesh","texture","normal-map","repair","reduce","compress","convert"]},"model":{"type":"string","description":"Models per tool: image-to-3d: trellis-2 (5), trellis-2-pro (15), hunyuan-3d-3-1-pro (90), tripo-3-1 (50), tripo-3-1-detailed (100); text-to-3d: trellis-2 (5), trellis-2-pro (15), hunyuan-3d-3-1-pro (90), tripo-3-1 (50), tripo-3-1-detailed (100); retexture: trellis-2-texture (5), trellis-2-texture-pro (10), tripo-texture (20), tripo-texture-detailed (40); remesh: instant-remesh (0), tripo-remesh (50); texture: flux-2-klein-material (2), muse-image-material (5), gpt-image-2-5-material (8); normal-map: none; repair: none; reduce: none; compress: none; convert: none"},"input":{"type":"object","properties":{"image":{"type":"string"},"mesh":{"type":"string"},"prompt":{"type":"string"}}},"options":{"type":"object"},"max_credits":{"type":"integer","minimum":0},"webhook_url":{"type":"string","format":"uri"}}},"Job":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"tool":{"type":"string"},"model":{"type":["string","null"]},"progress":{"type":"number"},"credits":{"type":"object","properties":{"price":{"type":"integer"},"charged":{"type":"integer"},"balance":{"type":"integer"}}},"output":{"type":["object","null"]},"asset_id":{"type":["string","null"]},"error":{"type":["object","null"]},"created_at":{"type":"string"},"finished_at":{"type":["string","null"]}}}}}}