Create Stunning 3D Assets with lucataco/hunyuan3d-2 Cognitive Actions

21 Apr 2025
Create Stunning 3D Assets with lucataco/hunyuan3d-2 Cognitive Actions

The lucataco/hunyuan3d-2 API provides a powerful toolset for developers looking to generate high-quality, textured 3D assets quickly and efficiently. Leveraging advanced diffusion models, these Cognitive Actions enable the creation of intricate 3D shapes with exceptional detail and texture quality. In this post, we'll explore how to use the "Generate High-Resolution 3D Textured Assets" action, which allows you to create stunning 3D models based on input images.

Prerequisites

Before you dive into the integration of Cognitive Actions, ensure you have an API key for accessing the Cognitive Actions platform. Authentication typically involves passing this API key in the headers of your requests. Make sure to set up your development environment to handle HTTP requests, as you'll be using these to call the actions.

Cognitive Actions Overview

Generate High-Resolution 3D Textured Assets

The Generate High-Resolution 3D Textured Assets action is designed to create high-quality, textured 3D assets using a scalable diffusion model. This operation, powered by the Hunyuan3D 2.0 system, utilizes a two-stage generation process that separates shape and texture creation, allowing for enhanced flexibility.

Input

The input for this action requires the following fields:

  • seed (integer, optional): An integer seed used for initializing random number generation for deterministic outputs. Default is 1234.
  • image (string, required): A URI pointing to the input image used for generating a 3D shape.
  • steps (integer, optional): Specifies the total number of inference steps to perform. Valid range is 20 to 50, with a default value of 50.
  • guidanceScale (number, optional): A number that influences the guidance on the generation process. It ranges from 1 to 20, with 5.5 as the default.
  • octreeResolution (integer, optional): Determines the resolution of the octree used in mesh generation. Options are 256, 384, or 512, with 256 set as the default.
  • removeBackground (boolean, optional): Indicates whether to remove the background from the input image. Defaults to true.

Here is an example of the JSON payload required to invoke this action:

{
  "seed": 1234,
  "image": "https://replicate.delivery/pbxt/MTXzbLBT7u5K94G3SnW61H37xL4zVyC4PZuwZAki3pxlgvK5/419.png",
  "steps": 50,
  "guidanceScale": 5.5,
  "octreeResolution": 256,
  "removeBackground": true
}

Output

Upon successful execution, the action typically returns a URL to the generated mesh file. Here’s an example of the output you can expect:

{
  "mesh": "https://assets.cognitiveactions.com/invocations/043e5ef4-5dec-4867-8afb-e29509e0b72a/2a5efcde-4ce0-472f-bc21-600294eea396.glb"
}

Conceptual Usage Example (Python)

Here’s a conceptual Python code snippet demonstrating how a developer might call the Cognitive Actions execution endpoint for the "Generate High-Resolution 3D Textured Assets" action:

import requests
import json

# Replace with your Cognitive Actions API key and endpoint
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"  # Hypothetical endpoint

action_id = "ca924563-e0e1-40ad-8372-635de4f35b3c"  # Action ID for Generate High-Resolution 3D Textured Assets

# Construct the input payload based on the action's requirements
payload = {
    "seed": 1234,
    "image": "https://replicate.delivery/pbxt/MTXzbLBT7u5K94G3SnW61H37xL4zVyC4PZuwZAki3pxlgvK5/419.png",
    "steps": 50,
    "guidanceScale": 5.5,
    "octreeResolution": 256,
    "removeBackground": True
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json"
}

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json={"action_id": action_id, "inputs": payload}  # Hypothetical structure
    )
    response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body: {e.response.text}")

In this code snippet, replace YOUR_COGNITIVE_ACTIONS_API_KEY with your actual API key. The payload variable contains the structured input required to call the action, and the request is sent to the hypothetical endpoint. The result is printed in a readable format.

Conclusion

The lucataco/hunyuan3d-2 Cognitive Action for generating high-resolution 3D textured assets offers developers a powerful tool for creating detailed 3D models from images. By utilizing this action, you can enhance your applications with stunning visual content effortlessly. Consider exploring additional use cases for this action or experimenting with different input parameters to achieve the desired results. Happy coding!

← Back to All Articles