English

中文

English

中文

Appearance

Create Task API ​

API Overview ​

Generate 3D models from input images.

ProtocolEndpointMethodAuthRequest FormatResponse Format
HTTP/open-api/v1/submit-taskPOSTBearermultipart/form-dataapplication/json

Request Headers ​

ParameterValueDescription
Content-Typemultipart/form-dataData exchange format
AuthorizationBearerReplace {accessToken} with the accessToken obtained above

Request Body (HTTP Form Submission) ​

ParameterTypeRequiredDescription
request_typeintYesRequest type, default is geometry+texture, which is 3
Enum values:
• 1: mesh, generate geometry only
• 2: texture, staged generation, generate textured model based on existing geometry model
• 3: both, generate geometry+texture model in one go
Note: v2.0 models (hitem3dv2.0, scene-portraitv2.0) do not support request_type=2
modelStringYesModel version, including general models and scene models, default
Enum values:
• General models: hitem3dv1, hitem3dv1.5, hitem3dv2.0
• Scene models: scene-portraitv1.5, scene-portraitv2.0
imagesfileYes, either with multi_imagesUpload image, the model will generate a 3D model based on the image passed in this parameter (single image-to-3D)
• Type: supports uploading form file submission
• Format: supports png, jpeg, .jpg, webp formats
• Size: image size not exceeding 20 MB
• Quantity: only supports input of 1 image
multi_imagesfileYes, either with imagesUpload image array, the model will generate a 3D model based on the images passed in this parameter (multi-view image-to-3D)
• Type: supports uploading form file submission
• Format: supports png, jpeg, .jpg, webp formats
• Size: single image size not exceeding 20 MB
• Quantity: maximum 4 images, in order of front view, back view, left view, right view
multi_images_bitstringNoUpload an array of bitmap images, used in conjunction with the multi_images field. For example, 1010 represents an image array of length 2, containing the front view and the left view.
resolutionstringNoResolution, default is 1024³
• v1.0 enum values: 512, 1024, 1536
• v1.5 enum values: 512, 1024, 1536, 1536pro
• v2.0 enum values: 1536, 1536pro
• scene-portraitv1.5 enum values: 1536
• scene-portraitv2.0 enum values: 1536pro
mesh_urlstringNoThe uploaded URL must be the GLB geometry model URL. Only GLB format is supported.
Used when request_type = 2 (“generate a textured model based on a geometry model”). When request_type = 2, either mesh_url or mesh must be provided.
Example: https://hitem3dstatic.zaohaowu.net/jjewelry/web/model3ds/img2model3d/20250722/79c8488490c2498785468e5203e77b6a/target//original/0.glb
meshfileNoUpload geometry model file directly in .glb format via HTTP form file upload. Only GLB format is supported.
Used when request_type = 2 (“generate a textured model based on a geometry model”). When request_type = 2, either mesh_url or mesh must be provided.
faceintNoModel face count, supports custom configuration, value range is 100000～2000000
Different resolutions correspond to different recommended face counts:
• 512³: 500000
• 1024³: 1000000
• 1536³: 2000000
• 1536³ Pro: 2000000
formatintNoFormat of the generated model, limited to one format, default is 1 obj format
Enum values:
• 1: obj
• 2: glb
• 3: stl
• 4: fbx
• 5: usdz
callback_urlStringOptionalCallback protocol
You need to actively set callback_url when creating a task. The request method is POST. When the model generation task has a status change, Hitem3D will send a callback request containing the latest task status to this address. The callback request content structure is consistent with the return body of the Query Task API
The "status" returned by the callback includes the following states:
• success: task completed (if sending fails, callback three times)
• failed: task failed (if sending fails, callback three times)

Response Body ​

ParameterFieldTypeDescription
code-StringError code, see error code table
datatask_idStringAsynchronous task ID generated by Hitem3D, results need to be obtained through the asynchronous task query interface using this ID.
msg-StringDetailed error message
json
{
    "code": 200,
    "data": {
        "task_id": "528f172b66554be2a2d1e95db4454a5a.jjewelry-aigc-api.7qbh5Z0wfR",
    },
    "msg": "success"
}

Error Codes ​

Error codes are returned in JSON structure, including code and msg fields. We will expand the corresponding field values with version updates.

json
{
    "code": 30010000,
    "data": {},
    "msg": "balance is not enough"
}
Error CodeError MessageError Description
30010000balance is not enoughInsufficient balance, please contact service provider to add credits
10031001Upload file size exceeds limitUploaded file exceeds 20MB
10031002Face not validInvalid face count, value range is 100000～2000000
10031003Resolution not validInvalid resolution, please refer to:
• v1.0 enum values: 512, 1024, 1536
• v1.5 enum values: 512, 1024, 1536, 1536pro
• v2.0 enum values: 1536, 1536pro
• scene-portraitv1.5 enum values: 1536
• scene-portraitv2.0 enum values: 1536pro
10031004request type not supportRequest type not supported, enum:
• 1: mesh, generate geometry only
• 2: texture, staged generation, generate textured model based on existing geometry model
• 3: both, generate geometry+texture model in one go
10031005images only allow png jpeg jpg webpImage type error, only png, jpeg, jpg, webp formats are supported
10031006model only allow hitem3dv1 hitem3dv1.5Model can only be hitem3dv1, hitem3dv1.5, hitem3dv2.0, scene-portraitv1.5, scene-portraitv2.0
10031007both images and multi images providedimages and multi_images cannot both be provided
10031008images or multi images requiredEither images or multi_images must be provided
10031009multi images count exceeds limitmulti_images supports up to 4 files
10031010empty file not allowedFile cannot be empty((Please submit using the appropriate HTTP form method; refer to the request example for details.))
10031011mesh url or mesh required when request type2When request_type is 2, either mesh_url or mesh must be provided
10031012mesh_url_must_start_with_httpmesh_url must start with http
10031013multi images bit length errormulti_images_bit length must be 4
10031014multi images bit invalid char errormulti_images_bit can only contain '0' and '1'
10031015multi_images_bit_count_mismatch_errorThe number of '1' in multi_images_bit must match the number of multi_images
10031016mesh format not supportedMesh format not supported. Only GLB format is supported for mesh_url and mesh
10031017model does not support textureThe requested model does not support texture generation (request_type=2). v2.0 models (hitem3dv2.0, scene-portraitv2.0) do not support request_type=2
10000000system errorSystem internal error

Request Examples (Shell & Python) ​

Shell - Image to 3D - All-in-One Generation （Geometry + Texture） ​

shell
curl --location --request POST 'https://api.hitem3d.ai/open-api/v1/submit-task' \
--header 'Authorization: Bearer 6pzBx1a5Cj68XhQe*H07YsrAYSIuSptfihGpHd40QTd3RtfRWy-ao9F12AqYUYdedxmbL0Yl2F8HO9nbhFuIs0hhoaJAd7GUAlgfp2nbHlqTJIBphEHgw_oVAtp9VQtN-mS_uUTwUejcENG4WzwAPtTsJBIZQzGjU_xJzZvnQPPPxaSQaPEBNsekNRFzMLq8us4W3zJJa8P3G0EVnQQ1_jhO6X4ycMBKfqS8GXALZntk-4vkykA4sZxU6edoQEjKGC6oT_dRK3GzevCxI1uvYvwmsNjZYe4G7uDlkNAuny6EdDiBqb3hpf4jETA_mv5ItAJvccd5S91_IJEV0v5uBALrkuD-bDuneLIi2h6-11et4gmAA5_00XgOq8OJDcJ3LUI71Jw==*WeNzV21CwM-cyccZ8BQmfNZn3hViOpTMLg1kJQnb0WI=' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Accept: */*' \
--header 'Host: api.hitem3d.ai' \
--header 'Connection: keep-alive' \
--header 'Content-Type: multipart/form-data; boundary=--------------------------606514836105993765865977' \
--form 'images=@"/Users/jinyeliu/Desktop/tos_temp/dog.jpeg"' \
--form 'request_type="3"' \
--form 'resolution="512"' \
--form 'face="800000"' \
--form 'mesh_url="https://mm-sparc3d-test.tos-ap-southeast-1.volces.com/jjewelry/web/model3ds/img2model3d/20250724/a483f649a77a4000961e82405bbd4439/target/model/original/0.glb"' \
--form 'model="hitem3dv1"' \
--form 'format="2"' \
--form 'callback_url="http://callback.com"'

Python - Image to 3D - Staged Generation（Geometry） ​

python
import requests

url = "https://api.hitem3d.ai/open-api/v1/submit-task"

headers = {
    "Authorization": "Bearer 6pzBx1a5Cj68XhQe*H07YsrAYSIuSptfihGpHd40QTd3RtfRWy-ao9F12AqYUYdedxmbL0Yl2F8HO9nbhFuIs0hhoaJAd7GUAlgfp2nbHlqTJIBphEHgw_oVAtp9VQtN-mS_uUTwUejcENG4WzwAPtTsJBIZQzGjU_xJzZvnQPPPxaSQaPEBNsekNRFzMLq8us4W3zJJa8P3G0EVnQQ1_jhO6X4ycMBKfqS8GXALZntk-4vkykA4sZxU6edoQEjKGC6oT_dRK3GzevCxI1uvYvwmsNjZYe4G7uDlkNAuny6EdDiBqb3hpf4jETA_mv5ItAJvccd5S91_IJEV0v5uBALrkuD-bDuneLIi2h6-11et4gmAA5_00XgOq8OJDcJ3LUI71Jw==*WeNzV21CwM-cyccZ8BQmfNZn3hViOpTMLg1kJQnb0WI=",
    "User-Agent": "Apifox/1.0.0 (https://apifox.com)",
    "Accept": "*/*",
    "Host": "api.hitem3d.ai",
    "Connection": "keep-alive"
}

files = {
    "images": ("glove_1.jpg", open("/Users/jinyeliu/Desktop/tos_temp/glove_1.jpg", "rb"), "image/jpeg")
}

data = {
    "request_type": "1",
    "resolution": "512",
    "face": "800000",
    "model": "hitem3dv1",
    "format": "2",
    "callback_url": "http://callback.com"
}

try:
    response = requests.post(
        url=url,
        headers=headers,
        files=files,
        data=data
    )

    print(f"Status Code: {response.status_code}")
    print(f"Response Content: {response.text}")

except Exception as e:
    print(f"Request Failed: {e}")

Python - Image to 3D - Staged Generation（Texture） (mesh_url required) ​

python
import requests

url = "https://api.hitem3d.ai/open-api/v1/submit-task"

headers = {
    "Authorization": "Bearer 6pzBx1a5Cj68XhQe*H07YsrAYSIuSptfihGpHd40QTd3RtfRWy-ao9F12AqYUYdedxmbL0Yl2F8HO9nbhFuIs0hhoaJAd7GUAlgfp2nbHlqTJIBphEHgw_oVAtp9VQtN-mS_uUTwUejcENG4WzwAPtTsJBIZQzGjU_xJzZvnQPPPxaSQaPEBNsekNRFzMLq8us4W3zJJa8P3G0EVnQQ1_jhO6X4ycMBKfqS8GXALZntk-4vkykA4sZxU6edoQEjKGC6oT_dRK3GzevCxI1uvYvwmsNjZYe4G7uDlkNAuny6EdDiBqb3hpf4jETA_mv5ItAJvccd5S91_IJEV0v5uBALrkuD-bDuneLIi2h6-11et4gmAA5_00XgOq8OJDcJ3LUI71Jw==*WeNzV21CwM-cyccZ8BQmfNZn3hViOpTMLg1kJQnb0WI=",
    "User-Agent": "Apifox/1.0.0 (https://apifox.com)",
    "Accept": "*/*",
    "Host": "api.hitem3d.ai",
    "Connection": "keep-alive"
}

files = {
    "images": ("glove_1.jpg", open("/Users/jinyeliu/Desktop/tos_temp/glove_1.jpg", "rb"), "image/jpeg")
}

data = {
    "request_type": "2",
    "resolution": "512",
    "face": "800000",
    "mesh_url": "https://hitem3dstatic.zaohaowu.net/jjewelry/web/model3ds/img2model3d/20250916/097772b01ec141c9b2f6711e0d98574a/target/model/original/0.glb",
    "model": "hitem3dv1",
    "format": "2",
    "callback_url": "http://callback.com"
}

try:
    response = requests.post(
        url=url,
        headers=headers,
        files=files,
        data=data
    )

    print(f"Status Code: {response.status_code}")
    print(f"Response Content: {response.text}")

except Exception as e:
    print(f"Request Failed: {e}")

Python - Image to 3D - All-in-One Generation（Geometry + Texture） ​

python
import requests

url = "https://api.hitem3d.ai/open-api/v1/submit-task"

headers = {
    "Authorization": "Bearer qFESV7ObldDU33ax*3MioO4CMXrhwjgDwtdpfrstSo_A2EccPyXkPcYhGjbUKpTTLI85ppChFMXCcqFjFk9l4Z9FQVn-XFBzksGmGleOJiCrX7z67b322mgbAoUmsMlFPlqNCcyn48lQHemP9iJI5x5WVFQgCJHcPKGewprUOqbTl5en0OUn6IRpxCHl8cRZj_M97N17I_LO46SG-vhfH0aiFeOU3sE-XilqkFVACb6WMjWOj-2s_XnGjfb-Hqq7GDD7JsilHU8pTNJFVhgrYn4LhVnvyRoNspkA7ksV0YmUxjmZt_1fCVvhzU47sSQcR6uZ-s8wxMai3F5E1fsDHyIDSM3dQRjP3OZ8BoC6u6PU3aZpY4isA_wZ21xZgHrMtbir86w==*_PCXp4sohWZh3pRv6Z3ZUtWuANcScv3mz5JLfgsr2Hg=",
    "User-Agent": "Apifox/1.0.0 (https://apifox.com)",
    "Accept": "*/*",
    "Host": "api.hitem3d.ai",
    "Connection": "keep-alive"
}

files = {
    "images": ("glove_1.jpg", open("/Users/jinyeliu/Desktop/tos_temp/glove_1.jpg", "rb"), "image/jpeg")
}

data = {
    "request_type": "3",
    "resolution": "512",
    "face": "800000",
    "model": "hitem3dv1",
    "format": "2",
    "callback_url": "http://callback.com"
}

try:
    response = requests.post(
        url=url,
        headers=headers,
        files=files,
        data=data
    )

    print(f"Status Code: {response.status_code}")
    print(f"Response Content: {response.text}")

except Exception as e:
    print(f"Request Failed: {e}")

Python - Multi-view to 3D -Staged Generation（Geometry） ​

python
import requests

url = "https://api.hitem3d.ai/open-api/v1/submit-task"

headers = {
    "Authorization": "Bearer qFESV7ObldDU33ax*3MioO4CMXrhwjgDwtdpfrstSo_A2EccPyXkPcYhGjbUKpTTLI85ppChFMXCcqFjFk9l4Z9FQVn-XFBzksGmGleOJiCrX7z67b322mgbAoUmsMlFPlqNCcyn48lQHemP9iJI5x5WVFQgCJHcPKGewprUOqbTl5en0OUn6IRpxCHl8cRZj_M97N17I_LO46SG-vhfH0aiFeOU3sE-XilqkFVACb6WMjWOj-2s_XnGjfb-Hqq7GDD7JsilHU8pTNJFVhgrYn4LhVnvyRoNspkA7ksV0YmUxjmZt_1fCVvhzU47sSQcR6uZ-s8wxMai3F5E1fsDHyIDSM3dQRjP3OZ8BoC6u6PU3aZpY4isA_wZ21xZgHrMtbir86w==*_PCXp4sohWZh3pRv6Z3ZUtWuANcScv3mz5JLfgsr2Hg=",
    "User-Agent": "Apifox/1.0.0 (https://apifox.com)",
    "Accept": "*/*",
    "Host": "api.hitem3d.ai",
    "Connection": "keep-alive"
}

data = {
    "request_type": "1",
    "resolution": "512",
    "face": "800000",
    "model": "hitem3dv1.5",
    "format": "2",
    "callback_url": "http://callback.com"
}

try:
    # Use with statement to ensure files are properly closed
    with open('/Users/jinyeliu/Desktop/tos_temp/monster_1.jpg', 'rb') as f1, \
            open('/Users/jinyeliu/Desktop/tos_temp/monster_2.jpg', 'rb') as f2:

        files = [
            ('multi_images', ('monster_1.jpg', f1, 'image/jpeg')),
            ('multi_images', ('monster_2.jpg', f2, 'image/jpeg'))
        ]

        response = requests.post(
            url=url,
            headers=headers,
            files=files,
            data=data
        )

        print(f"Status Code: {response.status_code}")
        print(f"Response Content: {response.text}")

except FileNotFoundError as e:
    print(f"File Not Found: {e}")
except Exception as e:
    print(f"Request Failed: {e}")

Python - Multi-view to 3D - Texture Stage (mesh_url required) ​

python
import requests

url = "https://api.hitem3d.ai/open-api/v1/submit-task"

headers = {
    "Authorization": "Bearer qFESV7ObldDU33ax*3MioO4CMXrhwjgDwtdpfrstSo_A2EccPyXkPcYhGjbUKpTTLI85ppChFMXCcqFjFk9l4Z9FQVn-XFBzksGmGleOJiCrX7z67b322mgbAoUmsMlFPlqNCcyn48lQHemP9iJI5x5WVFQgCJHcPKGewprUOqbTl5en0OUn6IRpxCHl8cRZj_M97N17I_LO46SG-vhfH0aiFeOU3sE-XilqkFVACb6WMjWOj-2s_XnGjfb-Hqq7GDD7JsilHU8pTNJFVhgrYn4LhVnvyRoNspkA7ksV0YmUxjmZt_1fCVvhzU47sSQcR6uZ-s8wxMai3F5E1fsDHyIDSM3dQRjP3OZ8BoC6u6PU3aZpY4isA_wZ21xZgHrMtbir86w==*_PCXp4sohWZh3pRv6Z3ZUtWuANcScv3mz5JLfgsr2Hg=",
    "User-Agent": "Apifox/1.0.0 (https://apifox.com)",
    "Accept": "*/*",
    "Host": "api.hitem3d.ai",
    "Connection": "keep-alive"
}

data = {
    "request_type": "2",
    "resolution": "512",
    "face": "800000",
    "mesh_url": "https://hitem3dstatic.zaohaowu.net/jjewelry/web/model3ds/img2model3d/20251016/337723bee83245c59b376cd4d5e1d6a2/target/model/original/0.glb",
    "model": "hitem3dv1.5",
    "format": "2",
    "callback_url": "http://callback.com"
}

try:
    # Use with statement to ensure files are properly closed
    with open('/Users/jinyeliu/Desktop/tos_temp/monster_1.jpg', 'rb') as f1, \
            open('/Users/dongshihao/Desktop/tos_temp/monster_2.jpg', 'rb') as f2:

        files = [
            ('multi_images', ('monster_1.jpg', f1, 'image/jpeg')),
            ('multi_images', ('monster_2.jpg', f2, 'image/jpeg'))
        ]

        response = requests.post(
            url=url,
            headers=headers,
            files=files,
            data=data
        )

        print(f"Status Code: {response.status_code}")
        print(f"Response Content: {response.text}")

except FileNotFoundError as e:
    print(f"File Not Found: {e}")
except Exception as e:
    print(f"Request Failed: {e}")

Python - Multi-view to 3D - All-in-One Generation（Geometry + Texture） ​

python
import requests

url = "https://api.hitem3d.ai/open-api/v1/submit-task"

headers = {
    "Authorization": "Bearer B6rqpUHM0aC_zt2m*Omp8grug1HuXkiFNXN1fBQURFdI8z0KSIb6npYnstS6hOjP6o_1mqVpo1qTTWjDodT4fIq8FpAxEmH_8BvjgmWiMzQztILzk3WJ9_jj3oGC-tCSxa-KsDhUAIipvp5OARw5roxwuDknrb2HqxcTlT9Fh4NJFBj9p-UCjrUVee9aCJjJ3B4u3IHn-ZyoXmqKZ_eDMdXiZ71XTxnQWT35nXwAIocjdg4QeP_kQWl2hBR4lyRKo4vvNJslVdhJF6o-pjuCMUfBxLrSbU8LmEFDtRbg88uSV3WoSXtZ3TWKH5auO6F1lgjwKRiwJ39BGKqwTaKnhsx8BLgMTji1yFK3DSg6kpwr7FKnAqiVl0OvjCDlgrT7xxbigJA==*zbm80LORI5z3xnMcthDnZuTyVL8lwvoT8gDIYWRSRsk=",
    "User-Agent": "Apifox/1.0.0 (https://apifox.com)",
    "Accept": "*/*",
    "Host": "api.hitem3d.ai",
    "Connection": "keep-alive"
}

data = {
    "request_type": "3",
    "resolution": "512",
    "face": "800000",
    "model": "hitem3dv1.5",
    "format": "2",
    "callback_url": "http://callback.com"
}

try:
    # Use with statement to ensure files are properly closed
    with open('/Users/jinyeliu/Desktop/tos_temp/monster_1.jpg', 'rb') as f1, \
            open('/Users/jinyeliu/Desktop/tos_temp/monster_2.jpg', 'rb') as f2:

        files = [
            ('multi_images', ('monster_1.jpg', f1, 'image/jpeg')),
            ('multi_images', ('monster_2.jpg', f2, 'image/jpeg'))
        ]

        response = requests.post(
            url=url,
            headers=headers,
            files=files,
            data=data
        )

        print(f"Status Code: {response.status_code}")
        print(f"Response Content: {response.text}")

except FileNotFoundError as e:
    print(f"File Not Found: {e}")
except Exception as e:
    print(f"Request Failed: {e}")

Copyright © 2025 Hitem3d