SculptOK API documentation
Read SculptOK API authentication, image upload, depth-map generation, AI 3D, image-to-STL conversion, task status and credit reference.
API reference
Credits
GET https://api.sculptok.com/api-open/point/info
Get the current Credits in the account
Request headers
{
"Content-Type": "application/json",
"apikey": "your_api_key"
}Response example
{
"code": 0,
"msg": "success",
"data": {
"point": 100
}
}Response fields
- point · number
- The current Credits in the account.
Error response example
{
"code": 401,
"msg": "Unauthorized",
"data": null
}Credits History
GET https://api.sculptok.com/api-open/point/page
Get the history of Credits in the account
Request headers
{
"Content-Type": "application/json",
"apikey": "your_api_key"
}Request parameters
{
"limit": 5,
"page": "1"
}Parameter details
- limit · number
- The number of returns of the current history
- page · string
- The postion of page
Response example
{
"code": 0,
"msg": "success",
"data": {
"total": 1,
"list": [
{
"id": "1888956880713715713",
"userId": "1881280564795301889",
"actionType": 5,
"remainValue": 26,
"changeNum": -10,
"remarks": "API Draw: 65c42194-af36-45ed-a833-4058b569622d",
"createDate": "2025-02-10 22:23:10"
}
]
}
}Response fields
- remainValue · number
- remaining Credits
- changeNum · number
- Number of Credits changed
- remarks · string
- Events that change Credits
Error response example
{
"code": 401,
"msg": "Unauthorized",
"data": null
}Upload Image
POST https://api.sculptok.com/api-open/image/upload
The first step to generate depth-map: Upload the image to the server
Request headers
{
"Content-Type": "multipart/form-data;",
"apikey": "your_api_key"
}Request body
{
"file": "image.jpg"
}Parameter details
- file · file · required
- The image you would like to upload.
Response example
{
"code": 0,
"msg": "success",
"data": {
"src": "https://mock/step_api/mock.png"
}
}Response fields
- src · string
- The address of the identifier returned for the successfully uploaded image.
Error response example
{
"code": 401,
"msg": "Unauthorized",
"data": null
}Submit Depth-Map Draw
POST https://api.sculptok.com/api-open/draw/prompt
After uploading an image, submit a depth-map task. Pro 1.0 and 1.5 support smoothing: true (default) uses the current smooth workflow; false restores the classic workflow. Pricing: base 10 Credits; Pro 2K costs 15 Credits; Pro 4K costs 30 Credits, including classic 4K EXR. With smoothing enabled, 4K EXR requests are downgraded to 2K before pricing.
Request headers
{
"Content-Type": "application/json",
"apikey": "your_api_key"
}Request body
{
"imageUrl": "https://example.com/uploaded-image.png",
"style": "pro",
"version": "1.5",
"smoothing": true,
"hd_fix": "manual",
"optimal_size": "false",
"draw_hd": "2k",
"extInfo": "16bit"
}Classic Pro 1.5 — smoothing off, historical 4K EXR
Set smoothing to false to restore the classic workflow. For this example, the EXR long side is 1536 px without super-resolution; the historical 4K tier does not mean a 4096 px EXR. Use version '1.0' for classic Pro 1.0.
{
"imageUrl": "https://example.com/uploaded-image.png",
"style": "pro",
"version": "1.5",
"smoothing": false,
"hd_fix": "manual",
"optimal_size": "false",
"draw_hd": "4k",
"extInfo": "exr"
}Parameter details
- imageUrl · string · required
- The Image Url from Upload Image API.
- style · string
- Type of image you uploaded. One of the following: normal, portrait, sketch, pro. Default: normal.
- hd_fix · string
- Enable or disable AI Optimization. Set to 'auto' to enable AI Optimization, or 'manual' to disable it. Default: manual.
- optimal_size · string
- Enable or disable optimal size. Set to 'true' to enable optimal size, or 'false' to disable it. Default: true.
- background_optimize · string
- Enable or disable depth-map Background Cleanup. Set to 'true' to enable cleanup, or 'false' to disable it. Default: false. This setting is independent of AI Optimization (hd_fix).
- extInfo · string
- Bit depth for the generated image. Default: 'false' (disabled). When enabled with '8bit', '16bit', or 'exr', only one image will be returned. EXR requires style='pro'. With smoothing enabled, EXR uses GPU super-resolution up to 1920 px on the longest side, and 4K EXR is downgraded to 2K. With smoothing=false, EXR uses the classic output size without super-resolution and retains the selected tier.
- version · string
- Model version, only effective when style is 'pro'. Default: 1.0. Options: 1.0, 1.5.
- smoothing · boolean
- Optional boolean for Pro 1.0 and 1.5. Default: true; omitting it or sending null also keeps the current smooth workflow. Set false to restore the classic generation workflow, including its original resolution behavior. This is independent of AI Optimization (hd_fix) and the Image-to-STL smart_denoise setting. Send JSON true or false, not a numeric strength.
- draw_hd · string
- Resolution preset for style='pro'. Default: 2k. With smoothing enabled, EXR is limited to 2K (up to 1920 px long side). With smoothing=false and optimal_size='false', classic EXR has a 1296 px long side at 2k or 1536 px at 4k; the short side is aligned to 8 px. The historical 4k tier is not a native 4096 px EXR. With optimal_size='true', classic automatic sizing applies instead.
Response example
{
"code": 0,
"msg": "success",
"data": {
"promptId": "4ffaf48f-6b00-4312-b592-2efb07597e93"
}
}Response fields
- promptId · string
- The identifier returned for the successfully submitted drawing.
Error response example
{
"code": 401,
"msg": "Unauthorized",
"data": null
}Background Removal/HD Restoration
POST https://api.sculptok.com/api-open/draw/hd/prompt
After upload image: Submit the Background Removal/HD Restoration task. Notice: Calling this API will cost 2 Credits.
Request headers
{
"Content-Type": "application/json",
"apikey": "your_api_key"
}Request body
{
"imageUrl": "https://mock.png",
"hdFix": "true",
"removeBack": "general"
}Parameter details
- imageUrl · string · required
- The Image Url from Upload Image API.
- hdFix · string
- If or not use HD Restoration, option: 'true' or 'false'.
- removeBack · string
- Type of Background Removal,option: 'anime' or 'general'。If null, background Removal will not be performed.
Response example
{
"code": 0,
"msg": "success",
"data": {
"promptId": "4ffaf48f-6b00-4312-b592-2efb07597e93"
}
}Response fields
- promptId · string
- The identifier returned for the successfully submitted drawing.
Error response example
{
"code": 401,
"msg": "Unauthorized",
"data": null
}Submit 3D Draw
POST https://api.sculptok.com/api-open/draw/3d/prompt
After upload image: Submit the 3D drawing task. Notice: Calling this API will cost 10 Credits.
Request headers
{
"Content-Type": "application/json",
"apikey": "your_api_key"
}Request body
{
"imageUrl": "https://mock.png"
}Parameter details
- imageUrl · string · required
- The Image Url from Upload Image API.
- hd_fix · string
- precision of image you uploaded. One of the following: basic, standard, high. Default: basic.
Response example
{
"code": 0,
"msg": "success",
"data": {
"promptId": "4ffaf48f-6b00-4312-b592-2efb07597e93"
}
}Response fields
- promptId · string
- The identifier returned for the successfully submitted drawing.
Error response example
{
"code": 401,
"msg": "Unauthorized",
"data": null
}Submit Image to STL
POST https://api.sculptok.com/api-open/draw/stl/prompt
After uploading a height map, submit an STL generation task. Contrast, Base Shape, Smart Denoise and Detail Protection use the same algorithms as the 3D preview. Successful STL tasks cost 3 Credits for files up to 200 MB, or 5 Credits total for files over 200 MB (1 MB = 1,000,000 bytes). Failed tasks are not charged. Conversion and upload may take up to 600 seconds. Use Drawing Status to retrieve the generated STL.
Request headers
{
"Content-Type": "application/json",
"apikey": "your_api_key"
}Request body
{
"image_url": "https://mock.png",
"width_mm": 120,
"min_thickness": 1.6,
"max_thickness": 5,
"invert": false,
"scale_image": 50,
"contrast": 1.5,
"base_shape": "square",
"smart_denoise": 0,
"detail_protection": 70,
"circular_scale": 100
}Parameter details
- image_url · string · required
- Input image URL, supports png/jpg/jpeg/webp/bmp/exr.
- width_mm · number
- Output model width (mm), range 40-240. Default: 120.0
- min_thickness · number
- Minimum thickness (mm), range 0.4-8 for darker areas before inversion. Default: 1.6
- max_thickness · number
- Maximum thickness (mm), range 0.4-25 for brighter areas before inversion; must be at least min_thickness. Also affects EXR contrast enhancement. Default: 5.0
- invert · boolean
- Invert grayscale after contrast and before denoising (black becomes thicker, white thinner). Default: false
- scale_image · number
- Image scale percent (0-100). Default: 50. The scaled image is then limited by max_side.
- contrast · number
- Contrast in the 3D preview, range 0.5-15. Default: 1.5. Uses the same power and S-curve mapping; EXR enhancement also depends on max_thickness.
- base_shape · string
- Base Shape in the 3D preview. square keeps the rectangular image; circular applies the same circular crop, edge feathering and closed boundary. If omitted, uses backplate_shape (default: square). Takes priority when both fields are supplied.
- smart_denoise · number
- Smart Denoise percentage, range 0-200. 0 disables denoising; 101-200 extends the smoothing strength. If omitted, uses blur_strength (default: 0). Takes priority over blur_strength, including an explicit 0.
- detail_protection · number
- Detail Protection percentage, range 0-100. Default: 70. 0 uses classic full-surface smoothing; 100 uses only the edge-preserving guided filter; intermediate values blend both. Has no effect when Smart Denoise is 0.
- circular_scale · number
- Circular Scale percentage, range 50-150. Default: 100. Only applies to circular bases. Values above 100 expand the grid around the image using the 3D preview's limits.
- max_side · number
- Maximum pixels per side after scaling, integer range 2-4096. Default for this public API: 4096. Lower values reduce mesh size and conversion time.
- backplate_enabled · boolean
- Close the back and side walls. Default: true. false enables Base Removal using base_removal_threshold.
- backplate_thickness · number
- Additional backplate thickness (mm), range 0-10. Default: 0. The closed back is at z=-backplate_thickness.
- base_removal_threshold · number
- Base Removal threshold, range 0.90-1.00. Default: 0.95. Applies when backplate_enabled is false.
- blur_strength · number
- Compatibility alias for Smart Denoise, range 0-200. Default: 0. Used only when smart_denoise is omitted.
- backplate_shape · string
- Compatibility alias for Base Shape. Default: square. Used only when base_shape is omitted.
Response example
{
"code": 0,
"msg": "success",
"data": {
"promptId": "4ffaf48f-6b00-4312-b592-2efb07597e93"
}
}Response fields
- promptId · string
- The identifier returned for the successfully submitted STL task.
Error response example
{
"code": 401,
"msg": "Unauthorized",
"data": null
}Drawing Status
GET https://api.sculptok.com/api-open/draw/prompt
Request headers
{
"Content-Type": "application/json",
"apikey": "your_api_key"
}Request parameters
{
"uuid": "4ffaf48f-6b00-4312-b592-2efb07597e93"
}Parameter details
- uuid · string · required
- The promptId from Submit Draw API.
Response example
{
"code": 0,
"msg": "success",
"data": {
"id": "1878376954302496770",
"currentStep": 3,
"status": 2,
"createDate": "2025-01-12 17:42:19",
"userId": "1828437318791659522",
"upImageUrl": "https://mock.png",
"promptId": "ef303479-d43c-4cfb-b78a-d6b813ff3488",
"imgRecords": [
"https://mock.png",
"https://mock.png",
"https://mock.png"
]
}
}Response fields
- upImageUrl · string
- The image URL of the uploaded image.
- position · number
- the position in the queue.
- imgRecords · array
- The image URL of generated depth-map. The total length is 3.
Error response example
{
"code": 401,
"msg": "Unauthorized",
"data": null
}Drawing History
GET https://api.sculptok.com/api-open/image/page
Request headers
{
"Content-Type": "application/json",
"apikey": "your_api_key"
}Request parameters
{
"page": 1,
"limit": 5
}Parameter details
- limit · number
- The number of returns of the drawing history
- page · number
- The postion of page
Response example
{
"code": 0,
"msg": "success",
"data": {
"total": 1,
"list": [
{
"id": "1878377197232390146",
"userId": "1828437318791659522",
"imgUrl": "https://mock.png",
"createDate": "2025-01-12 17:43:17"
}
]
}
}Response fields
- imgUrl · string
- The image URL of generated depth-map.
Error response example
{
"code": 401,
"msg": "Unauthorized",
"data": null
}Price
PRICE https://api.sculptok.com/api-open/image/page
Request headers
{
"Content-Type": "application/json",
"apikey": "your_api_key"
}Request parameters
{
"page": 1,
"limit": 5
}Parameter details
- limit · number
- The number of returns of the drawing history
- page · number
- The postion of page
Response example
{
"code": 0,
"msg": "success",
"data": {
"total": 1,
"list": [
{
"id": "1878377197232390146",
"userId": "1828437318791659522",
"imgUrl": "https://mock.png",
"createDate": "2025-01-12 17:43:17"
}
]
}
}Response fields
- imgUrl · string
- The image URL of generated depth-map.
Error response example
{
"code": 401,
"msg": "Unauthorized",
"data": null
}API Key
KEY https://api.sculptok.com/api-open/image/page
Request headers
{
"Content-Type": "application/json",
"apikey": "your_api_key"
}Request parameters
{
"page": 1,
"limit": 5
}Parameter details
- limit · number
- The number of returns of the drawing history
- page · number
- The postion of page
Response example
{
"code": 0,
"msg": "success",
"data": {
"total": 1,
"list": [
{
"id": "1878377197232390146",
"userId": "1828437318791659522",
"imgUrl": "https://mock.png",
"createDate": "2025-01-12 17:43:17"
}
]
}
}Response fields
- imgUrl · string
- The image URL of generated depth-map.
Error response example
{
"code": 401,
"msg": "Unauthorized",
"data": null
}