{
  "openapi": "3.1.0",
  "info": {
    "title": "Tencent HY 3D Global Create API",
    "version": "1.0.0",
    "description": "Create an asynchronous Tencent HY 3D Global (Hunyuan 3D) image-to-3D job with model version 3.1."
  },
  "servers": [
    {
      "url": "https://api.cometapi.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/hunyuan3d/v1/jobs": {
      "post": {
        "summary": "Create a Tencent HY 3D Global (Hunyuan 3D) job",
        "operationId": "create_tencent_hy_3d_global_job",
        "description": "Create an asynchronous image-to-3D job from a Base64 image. Store the returned `job_id`, wait 30 seconds, then retrieve the job.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTencentHY3DGlobalJobRequest"
              },
              "examples": {
                "Base64 image — Normal": {
                  "summary": "Create a textured model from a Base64 image",
                  "value": {
                    "Action": "SubmitHunyuanTo3DProJob",
                    "Model": "3.1",
                    "ImageBase64": "<base64-encoded-image>",
                    "GenerateType": "Normal"
                  }
                },
                "Base64 image — Geometry": {
                  "summary": "Create an untextured geometry model from a Base64 image",
                  "value": {
                    "Action": "SubmitHunyuanTo3DProJob",
                    "Model": "3.1",
                    "ImageBase64": "<base64-encoded-image>",
                    "GenerateType": "Geometry"
                  }
                },
                "PBR materials": {
                  "summary": "Request PBR materials for a textured model",
                  "value": {
                    "Action": "SubmitHunyuanTo3DProJob",
                    "Model": "3.1",
                    "ImageBase64": "<base64-encoded-image>",
                    "GenerateType": "Normal",
                    "EnablePBR": true
                  }
                },
                "Target face count": {
                  "summary": "Request a target mesh density",
                  "value": {
                    "Action": "SubmitHunyuanTo3DProJob",
                    "Model": "3.1",
                    "ImageBase64": "<base64-encoded-image>",
                    "GenerateType": "Normal",
                    "FaceCount": 100000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job accepted. Store the returned job ID and use it with the retrieve endpoint.",
            "headers": {
              "X-Cometapi-Request-Id": {
                "description": "CometAPI response-header request identifier for troubleshooting. Keep it with the body `request_id`; do not assume the values match.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateTencentHY3DGlobalJobResponse"
                },
                "example": {
                  "job_id": "<job_id>",
                  "request_id": "<request_id>"
                }
              }
            }
          },
          "400": {
            "description": "The request could not be processed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "Base64 image — Normal",
            "source": "curl \"https://api.cometapi.com/hunyuan3d/v1/jobs\" \\\n  --request POST \\\n  --header \"Authorization: Bearer $COMETAPI_KEY\" \\\n  --header \"Content-Type: application/json\" \\\n  --data-binary @- <<'JSON'\n{\n  \"Action\": \"SubmitHunyuanTo3DProJob\",\n  \"Model\": \"3.1\",\n  \"ImageBase64\": \"<base64-encoded-png>\",\n  \"GenerateType\": \"Normal\"\n}\nJSON\n"
          },
          {
            "lang": "Python",
            "label": "Base64 image — Normal",
            "source": "import base64\nimport os\nimport requests\n\nwith open(\"source.png\", \"rb\") as image_file:\n    image_base64 = base64.b64encode(image_file.read()).decode(\"ascii\")\n\nresponse = requests.post(\n    \"https://api.cometapi.com/hunyuan3d/v1/jobs\",\n    headers={\"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"]},\n    json={\n        \"Action\": \"SubmitHunyuanTo3DProJob\",\n        \"Model\": \"3.1\",\n        \"ImageBase64\": image_base64,\n        \"GenerateType\": \"Normal\",\n    },\n    timeout=60,\n)\nresponse.raise_for_status()\nprint(response.json()[\"job_id\"])\n"
          },
          {
            "lang": "JavaScript",
            "label": "Base64 image — Normal",
            "source": "import { readFile } from \"node:fs/promises\";\n\nconst imageBase64 = (await readFile(\"source.png\")).toString(\"base64\");\nconst response = await fetch(\"https://api.cometapi.com/hunyuan3d/v1/jobs\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    Action: \"SubmitHunyuanTo3DProJob\",\n    Model: \"3.1\",\n    ImageBase64: imageBase64,\n    GenerateType: \"Normal\",\n  }),\n});\nif (!response.ok) {\n  throw new Error(`Request failed with status ${response.status}`);\n}\nconsole.log((await response.json()).job_id);\n"
          },
          {
            "lang": "Shell",
            "label": "Base64 image — Geometry",
            "source": "curl \"https://api.cometapi.com/hunyuan3d/v1/jobs\" \\\n  --request POST \\\n  --header \"Authorization: Bearer $COMETAPI_KEY\" \\\n  --header \"Content-Type: application/json\" \\\n  --data-binary @- <<'JSON'\n{\n  \"Action\": \"SubmitHunyuanTo3DProJob\",\n  \"Model\": \"3.1\",\n  \"ImageBase64\": \"<base64-encoded-png>\",\n  \"GenerateType\": \"Geometry\"\n}\nJSON\n"
          },
          {
            "lang": "Python",
            "label": "Base64 image — Geometry",
            "source": "import base64\nimport os\nimport requests\n\nwith open(\"source.png\", \"rb\") as image_file:\n    image_base64 = base64.b64encode(image_file.read()).decode(\"ascii\")\n\nresponse = requests.post(\n    \"https://api.cometapi.com/hunyuan3d/v1/jobs\",\n    headers={\"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"]},\n    json={\n        \"Action\": \"SubmitHunyuanTo3DProJob\",\n        \"Model\": \"3.1\",\n        \"ImageBase64\": image_base64,\n        \"GenerateType\": \"Geometry\",\n    },\n    timeout=60,\n)\nresponse.raise_for_status()\nprint(response.json()[\"job_id\"])\n"
          },
          {
            "lang": "JavaScript",
            "label": "Base64 image — Geometry",
            "source": "import { readFile } from \"node:fs/promises\";\n\nconst imageBase64 = (await readFile(\"source.png\")).toString(\"base64\");\nconst response = await fetch(\"https://api.cometapi.com/hunyuan3d/v1/jobs\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    Action: \"SubmitHunyuanTo3DProJob\",\n    Model: \"3.1\",\n    ImageBase64: imageBase64,\n    GenerateType: \"Geometry\",\n  }),\n});\nif (!response.ok) {\n  throw new Error(`Request failed with status ${response.status}`);\n}\nconsole.log((await response.json()).job_id);\n"
          },
          {
            "lang": "Shell",
            "label": "PBR materials",
            "source": "curl \"https://api.cometapi.com/hunyuan3d/v1/jobs\" \\\n  --request POST \\\n  --header \"Authorization: Bearer $COMETAPI_KEY\" \\\n  --header \"Content-Type: application/json\" \\\n  --data-binary @- <<'JSON'\n{\n  \"Action\": \"SubmitHunyuanTo3DProJob\",\n  \"Model\": \"3.1\",\n  \"ImageBase64\": \"<base64-encoded-png>\",\n  \"GenerateType\": \"Normal\",\n  \"EnablePBR\": true\n}\nJSON\n"
          },
          {
            "lang": "Python",
            "label": "PBR materials",
            "source": "import base64\nimport os\nimport requests\n\nwith open(\"source.png\", \"rb\") as image_file:\n    image_base64 = base64.b64encode(image_file.read()).decode(\"ascii\")\n\nresponse = requests.post(\n    \"https://api.cometapi.com/hunyuan3d/v1/jobs\",\n    headers={\"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"]},\n    json={\n        \"Action\": \"SubmitHunyuanTo3DProJob\",\n        \"Model\": \"3.1\",\n        \"ImageBase64\": image_base64,\n        \"GenerateType\": \"Normal\",\n        \"EnablePBR\": True,\n    },\n    timeout=60,\n)\nresponse.raise_for_status()\nprint(response.json()[\"job_id\"])\n"
          },
          {
            "lang": "JavaScript",
            "label": "PBR materials",
            "source": "import { readFile } from \"node:fs/promises\";\n\nconst imageBase64 = (await readFile(\"source.png\")).toString(\"base64\");\nconst response = await fetch(\"https://api.cometapi.com/hunyuan3d/v1/jobs\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    Action: \"SubmitHunyuanTo3DProJob\",\n    Model: \"3.1\",\n    ImageBase64: imageBase64,\n    GenerateType: \"Normal\",\n    EnablePBR: true,\n  }),\n});\nif (!response.ok) {\n  throw new Error(`Request failed with status ${response.status}`);\n}\nconsole.log((await response.json()).job_id);\n"
          },
          {
            "lang": "Shell",
            "label": "Target face count",
            "source": "curl \"https://api.cometapi.com/hunyuan3d/v1/jobs\" \\\n  --request POST \\\n  --header \"Authorization: Bearer $COMETAPI_KEY\" \\\n  --header \"Content-Type: application/json\" \\\n  --data-binary @- <<'JSON'\n{\n  \"Action\": \"SubmitHunyuanTo3DProJob\",\n  \"Model\": \"3.1\",\n  \"ImageBase64\": \"<base64-encoded-png>\",\n  \"GenerateType\": \"Normal\",\n  \"FaceCount\": 100000\n}\nJSON\n"
          },
          {
            "lang": "Python",
            "label": "Target face count",
            "source": "import base64\nimport os\nimport requests\n\nwith open(\"source.png\", \"rb\") as image_file:\n    image_base64 = base64.b64encode(image_file.read()).decode(\"ascii\")\n\nresponse = requests.post(\n    \"https://api.cometapi.com/hunyuan3d/v1/jobs\",\n    headers={\"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"]},\n    json={\n        \"Action\": \"SubmitHunyuanTo3DProJob\",\n        \"Model\": \"3.1\",\n        \"ImageBase64\": image_base64,\n        \"GenerateType\": \"Normal\",\n        \"FaceCount\": 100000,\n    },\n    timeout=60,\n)\nresponse.raise_for_status()\nprint(response.json()[\"job_id\"])\n"
          },
          {
            "lang": "JavaScript",
            "label": "Target face count",
            "source": "import { readFile } from \"node:fs/promises\";\n\nconst imageBase64 = (await readFile(\"source.png\")).toString(\"base64\");\nconst response = await fetch(\"https://api.cometapi.com/hunyuan3d/v1/jobs\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.COMETAPI_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    Action: \"SubmitHunyuanTo3DProJob\",\n    Model: \"3.1\",\n    ImageBase64: imageBase64,\n    GenerateType: \"Normal\",\n    FaceCount: 100000,\n  }),\n});\nif (!response.ok) {\n  throw new Error(`Request failed with status ${response.status}`);\n}\nconsole.log((await response.json()).job_id);\n"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer authentication. Use your CometAPI API key."
      }
    },
    "schemas": {
      "CreateTencentHY3DGlobalJobRequest": {
        "type": "object",
        "required": [
          "Action",
          "Model",
          "ImageBase64"
        ],
        "properties": {
          "Action": {
            "type": "string",
            "const": "SubmitHunyuanTo3DProJob",
            "description": "Tencent HY 3D Global operation name. Must be `SubmitHunyuanTo3DProJob`."
          },
          "Model": {
            "type": "string",
            "const": "3.1",
            "description": "Tencent HY 3D Global model version. Must be `3.1`."
          },
          "ImageBase64": {
            "type": "string",
            "minLength": 1,
            "contentEncoding": "base64",
            "description": "Base64-encoded primary image without a data URL prefix. Supported formats are JPG, JPEG, PNG, and WebP. Each side must be from 128 through 5,000 pixels. The encoded value must be at most 8 MB; keep the source file at or below 6 MB to allow for encoding overhead.",
            "example": "<base64-encoded-image>"
          },
          "GenerateType": {
            "type": "string",
            "enum": [
              "Normal",
              "Geometry"
            ],
            "default": "Normal",
            "description": "Generation mode. Choose `Normal` for textured output or `Geometry` for geometry-only output."
          },
          "EnablePBR": {
            "type": "boolean",
            "default": false,
            "description": "Whether to add physically based rendering (PBR) material maps to the OBJ and MTL resource bundle for a `Normal` job."
          },
          "FaceCount": {
            "type": "integer",
            "minimum": 3000,
            "maximum": 1500000,
            "default": 500000,
            "description": "Target face count for the generated mesh. Treat this value as a target rather than an exact polygon guarantee.",
            "example": 100000
          }
        },
        "additionalProperties": false
      },
      "CreateTencentHY3DGlobalJobResponse": {
        "type": "object",
        "required": [
          "job_id",
          "request_id"
        ],
        "properties": {
          "job_id": {
            "type": "string",
            "minLength": 1,
            "description": "Job identifier. Use it to retrieve the job.",
            "example": "<job_id>"
          },
          "request_id": {
            "type": "string",
            "minLength": 1,
            "description": "Body request identifier for the create operation. Keep it with the `X-Cometapi-Request-Id` response header when troubleshooting.",
            "example": "<request_id>"
          }
        },
        "additionalProperties": false
      },
      "ErrorResponse": {
        "description": "Error body returned when the request cannot be processed.",
        "type": "object",
        "additionalProperties": true
      }
    }
  }
}