Transform Your Images into 3D Assets with firtoz/trellis Cognitive Actions

22 Apr 2025
Transform Your Images into 3D Assets with firtoz/trellis Cognitive Actions

In the world of 3D modeling and rendering, generating high-quality assets from 2D images can be a game-changer for developers and designers alike. The firtoz/trellis API offers a powerful Cognitive Action called Generate 3D Assets, which allows you to transform input images into detailed 3D assets. This action is capable of producing outputs in various formats, such as GLB files, radiance fields, and textured meshes, making it an invaluable tool for enhancing applications that require 3D content.

Prerequisites

To get started with using the Cognitive Actions, you will need to have the following:

  • An API key for the Cognitive Actions platform.
  • Familiarity with JSON data structures.
  • Basic understanding of making HTTP requests.

Authentication typically involves passing your API key in the request headers.

Cognitive Actions Overview

Generate 3D Assets

The Generate 3D Assets action is designed to convert a set of input images into 3D models and associated media. This is particularly useful for applications in gaming, virtual reality, and product visualization.

Input: The action requires a JSON payload with the following schema:

{
  "seed": 0,
  "images": [
    "uri_of_image_1",
    "uri_of_image_2",
    "uri_of_image_3"
  ],
  "textureSize": 2048,
  "meshSimplify": 0.9,
  "generateColor": true,
  "generateModel": true,
  "randomizeSeed": true,
  "generateNormal": false,
  "sparseStructureSamplingSteps": 12,
  "structuredLatentSamplingSteps": 12,
  "sparseStructureGuidanceStrength": 7.5,
  "structuredLatentGuidanceStrength": 3
}

Example Input:

{
  "seed": 0,
  "images": [
    "https://replicate.delivery/pbxt/MClj4HeBGlMw8Jwr8nRJgG4gtSMuIzHYZmsV2XKeJkYtqFYg/yoimiya_3.png",
    "https://replicate.delivery/pbxt/MClj53w5pbLeLnZuBtDdhqIyolFZBXJ30nlM2d3IeCNfbawR/yoimiya_2.png",
    "https://replicate.delivery/pbxt/MClj4vk3vYcbRp88EPypUzwUnJFScjLLEqTDgVNKiQg2LiRS/yoimiya_1.png"
  ],
  "textureSize": 2048,
  "meshSimplify": 0.9,
  "generateColor": true,
  "generateModel": true,
  "randomizeSeed": true,
  "generateNormal": false,
  "sparseStructureSamplingSteps": 12,
  "structuredLatentSamplingSteps": 12,
  "sparseStructureGuidanceStrength": 7.5,
  "structuredLatentGuidanceStrength": 3
}

Output: The action typically returns the following structure:

{
  "model_file": "uri_to_glb_file",
  "color_video": "uri_to_color_video",
  "normal_video": null,
  "combined_video": null,
  "no_background_images": null
}

Example Output:

{
  "model_file": "https://assets.cognitiveactions.com/invocations/316087d6-4ddb-4173-9cb8-86f0bfd362c8/5b755063-24b3-4880-8461-3514c25873b4.glb",
  "color_video": "https://assets.cognitiveactions.com/invocations/316087d6-4ddb-4173-9cb8-86f0bfd362c8/f7b0daa1-9ecf-48cf-b236-ec8b4f992500.mp4",
  "normal_video": null,
  "combined_video": null,
  "no_background_images": null
}

Conceptual Usage Example (Python): Here's how you might call the Generate 3D Assets action using a hypothetical endpoint:

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 = "4c17f4de-4aef-4cd2-af11-ac2b17cb2c52"  # Action ID for Generate 3D Assets

# Construct the input payload based on the action's requirements
payload = {
    "seed": 0,
    "images": [
        "https://replicate.delivery/pbxt/MClj4HeBGlMw8Jwr8nRJgG4gtSMuIzHYZmsV2XKeJkYtqFYg/yoimiya_3.png",
        "https://replicate.delivery/pbxt/MClj53w5pbLeLnZuBtDdhqIyolFZBXJ30nlM2d3IeCNfbawR/yoimiya_2.png",
        "https://replicate.delivery/pbxt/MClj4vk3vYcbRp88EPypUzwUnJFScjLLEqTDgVNKiQg2LiRS/yoimiya_1.png"
    ],
    "textureSize": 2048,
    "meshSimplify": 0.9,
    "generateColor": true,
    "generateModel": true,
    "randomizeSeed": true,
    "generateNormal": false,
    "sparseStructureSamplingSteps": 12,
    "structuredLatentSamplingSteps": 12,
    "sparseStructureGuidanceStrength": 7.5,
    "structuredLatentGuidanceStrength": 3
}

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 example, the action ID and input payload are appropriately structured for the API call. Note that the endpoint URL and specific request structure are illustrative and should be adapted as necessary.

Conclusion

The Generate 3D Assets action from the firtoz/trellis API offers a robust solution for developers looking to integrate 3D modeling capabilities into their applications. By transforming images into detailed 3D assets, you can significantly enhance user experiences in various fields, from gaming to architecture. As you explore this action, consider experimenting with different input parameters to optimize the outputs for your specific needs. Happy coding!

← Back to All Articles