SculptOKLoading…
SculptOK

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
}