> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-for-blender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hunyuan3D Integration: Tencent AI 3D Generation

> Generate 3D models from text or images using Hunyuan3D by Tencent inside Blender MCP, supporting both Official API and Local API modes.

Hunyuan3D is Tencent's AI 3D generation model. Blender MCP supports two modes: Official API through Tencent Cloud and Local API for self-hosted instances. Like Hyper3D Rodin, it excels at generating single objects from a text description or reference image, giving you an alternative when you already have a Tencent Cloud account or prefer a self-hosted pipeline.

## Setup

The setup depends on which mode you use.

<Tabs>
  <Tab title="Official API">
    <Steps>
      <Step>
        Get your **SecretId** and **SecretKey** from [cloud.tencent.com](https://cloud.tencent.com).
      </Step>

      <Step>
        In Blender, go to **Edit → Preferences → Add-ons → Blender MCP**.
      </Step>

      <Step>
        Enter your credentials in the Hunyuan3D fields.
      </Step>
    </Steps>

    Alternatively, set the environment variables before starting Blender:

    ```bash theme={null}
    export BLENDERMCP_HUNYUAN3D_SECRET_ID="your-secret-id"
    export BLENDERMCP_HUNYUAN3D_SECRET_KEY="your-secret-key"
    ```
  </Tab>

  <Tab title="Local API">
    <Steps>
      <Step>
        Set up your self-hosted Hunyuan3D instance.
      </Step>

      <Step>
        In Blender, go to **Edit → Preferences → Add-ons → Blender MCP**.
      </Step>

      <Step>
        Enter your local API URL in the **Hunyuan3D API URL** field.
      </Step>
    </Steps>

    Alternatively, set the environment variable:

    ```bash theme={null}
    export BLENDERMCP_HUNYUAN3D_API_URL="http://localhost:8080"
    ```
  </Tab>
</Tabs>

## Official API Workflow

When using the Official API, generation follows an asynchronous three-step process:

<Steps>
  <Step>
    **Create task** — Call `generate_hunyuan3d_model(text_prompt)` or pass an image URL to start generation. This returns a job ID.
  </Step>

  <Step>
    **Poll** — Call `poll_hunyuan_job_status(job_id)` repeatedly until the status returns `DONE`.
  </Step>

  <Step>
    **Import** — Call `import_generated_asset_hunyuan(name, zip_file_url)` to download and place the model. Prefer the `.glb` URL from `ResultFile3Ds` if available.
  </Step>
</Steps>

## Local API Workflow

When using the Local API, the process is simpler. Call `generate_hunyuan3d_model(text_prompt)` or pass an image, and the tool handles the full flow in a single call. No manual polling is required.

<Warning>
  Blender must be running with a GUI, not headless. After import, check the world bounding box and adjust location, scale, and rotation as needed.
</Warning>

## Best For

Use Hunyuan3D when you need single custom objects not available in asset libraries. It is a strong alternative to Hyper3D Rodin if you already have a Tencent Cloud account or want a fully self-hosted generation pipeline.

<CardGroup cols={2}>
  <Card title="Tencent Cloud Users" icon="cloud">
    Ideal if you already have Tencent Cloud credentials and want to reuse them for 3D generation.
  </Card>

  <Card title="Self-Hosted Workflows" icon="server">
    Run generation locally without relying on external cloud services or rate limits.
  </Card>
</CardGroup>