Generate Stunning 3D Assets with Hunyuan3D Cognitive Actions

23 Apr 2025
Generate Stunning 3D Assets with Hunyuan3D Cognitive Actions

In the world of 3D modeling and asset creation, the ndreca/hunyuan3d-2 API offers powerful Cognitive Actions that streamline the process of generating high-resolution, textured 3D assets from input images. Utilizing advanced scaled diffusion models, these actions allow developers to create intricate 3D shapes with features like background removal and customizable resolution settings. By leveraging these pre-built actions, you can save time and resources while enhancing your application's visual capabilities.

Prerequisites

Before diving into the Cognitive Actions, ensure you have the following in place:

  • An API key for the Cognitive Actions platform to authenticate your requests.
  • Familiarity with JSON and the ability to make HTTP requests from your development environment.

Authentication is typically handled by including your API key in the request headers.

Cognitive Actions Overview

Generate High Resolution 3D Textured Assets

The Generate High Resolution 3D Textured Assets action enables the creation of detailed 3D assets from a provided image. This action supports various configurations, allowing you to control aspects such as the number of inference steps and the level of background removal.

Input

The input for this action is structured as follows:

  • seed (integer, optional): Random seed for generation, used to ensure reproducibility. Defaults to 1234.
  • image (string, required): URL of the input image used for generating a 3D shape. Must be in URI format.
  • steps (integer, optional): Number of inference steps to perform. Must be between 20 and 50. Defaults to 50.
  • guidanceScale (number, optional): Scale factor guiding the model's output. Must be between 1 and 20. Defaults to 5.5.
  • octreeResolution (integer, optional): Resolution setting for mesh generation using octrees. Options are 256, 384, and 512. Defaults to 256.
  • removeBackground (boolean, optional): Specifies whether to remove the background from the input image. Defaults to true.

Example Input:

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

Output

When executed successfully, this action returns a JSON response containing the URL of the generated 3D mesh.

Example Output:

{
  "mesh": "https://assets.cognitiveactions.com/invocations/46ec2f4e-dac1-4f24-aef3-78c62fb5eb9d/34710152-a8d8-4fe1-b5f9-2f822cfc9324.glb"
}

Conceptual Usage Example (Python)

Here’s a conceptual Python code snippet illustrating how you might invoke this 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 = "12abcf1a-8c53-4d2d-8cac-9af7935d82c1"  # 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/MVC2B2XKgv4X13qIpW6t2m59EVfY2CqaS9e2CSsWNHPJjQAd/image.png",
    "steps": 50,
    "guidanceScale": 5.5,
    "octreeResolution": 512,
    "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}")

This code snippet outlines the process of constructing the input JSON payload, authenticating the request, and handling the response. Make sure to replace the API key and endpoint with your actual credentials.

Conclusion

The ndreca/hunyuan3d-2 Cognitive Actions provide developers with the tools to easily generate high-resolution 3D textured assets from images, streamlining the asset creation process in various applications. With customizable parameters and straightforward integration, these actions can enhance your projects significantly. Explore further use cases, experiment with different input settings, and unleash your creativity in the realm of 3D modeling!

← Back to All Articles