Create Stunning Depth-Aware Images with black-forest-labs/flux-depth-pro Actions

21 Apr 2025
Create Stunning Depth-Aware Images with black-forest-labs/flux-depth-pro Actions

In the world of digital media, the ability to generate depth-aware images is a game-changer. The black-forest-labs/flux-depth-pro API provides developers with a powerful Cognitive Action designed to create images that maintain spatial relationships and 3D structures. This functionality opens up a plethora of possibilities for applications in architectural visualization, product placement, and style transfer while preserving depth. By leveraging this pre-built action, developers can save time and resources, focusing instead on enhancing their applications with stunning visuals.

Prerequisites

Before diving into the integration of the Cognitive Actions, ensure you have the following:

  • An API key for accessing the Cognitive Actions platform.
  • Basic familiarity with JSON and HTTP requests.
  • Python installed on your development environment for executing the provided code snippets.

Authentication can be done by passing your API key in the request headers, ensuring secure access to the action endpoints.

Cognitive Actions Overview

Generate Depth-Aware Images

The Generate Depth-Aware Images action allows you to create images that not only look visually appealing but also retain depth perception. This is particularly useful for applications that require a realistic representation of 3D spaces.

Input: The input for this action consists of several fields, both required and optional, defined in the schema below.

{
  "controlImage": "https://example.com/image.jpg",
  "prompt": "abstract 3D render with the word \"DEPTH\"",
  "seed": 123,
  "steps": 50,
  "guidance": 7,
  "outputFormat": "jpg",
  "safetyTolerance": 2,
  "promptUpsampling": false
}
  • controlImage (required): A URL pointing to the control image (jpeg, png, gif, or webp).
  • prompt (required): A textual prompt that guides the image generation process.
  • seed (optional): A random seed value for reproducibility.
  • steps (optional): Number of diffusion steps (15 to 50). Higher values yield finer detail.
  • guidance (optional): Controls adherence to the prompt (1-100). Higher values match the prompt more closely.
  • outputFormat (optional): Specifies the output file format ('jpg' or 'png'). Default is 'jpg'.
  • safetyTolerance (optional): Level of safety tolerance for content generation (1-6).
  • promptUpsampling (optional): Automatically enhances the text prompt for more creative images.

Example Input:

{
  "steps": 50,
  "prompt": "abstract 3D render with the word \"DEPTH\"",
  "guidance": 7,
  "controlImage": "https://replicate.delivery/pbxt/M0ivr5QCMktmdUi3t0TFrKtw3DSPenPTU5NAOEKjTfW98HaB/https___replicate.delivery_czjl_z4gE33oPjuLPB91f9eO5Np4zaqwm20UYPOZhjpTfXRJVzYmnA_tmppi3by3z7.jpg",
  "outputFormat": "jpg",
  "safetyTolerance": 2,
  "promptUpsampling": false
}

Output: Upon successful execution, this action returns a URL to the generated depth-aware image.

Example Output:

https://assets.cognitiveactions.com/invocations/aae9a968-c7c6-4f5c-9dec-c9b907cf3b06/ab3516fa-8555-43f1-b45c-e6d4a8a90140.jpg

Conceptual Usage Example (Python): Here’s how you might call the Generate Depth-Aware Images action using Python:

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 = "1d8f9041-0cbd-4391-a357-5eb60a338d9f"  # Action ID for Generate Depth-Aware Images

# Construct the input payload based on the action's requirements
payload = {
    "steps": 50,
    "prompt": "abstract 3D render with the word \"DEPTH\"",
    "guidance": 7,
    "controlImage": "https://replicate.delivery/pbxt/M0ivr5QCMktmdUi3t0TFrKtw3DSPenPTU5NAOEKjTfW98HaB/https___replicate.delivery_czjl_z4gE33oPjuLPB91f9eO5Np4zaqwm20UYPOZhjpTfXRJVzYmnA_tmppi3by3z7.jpg",
    "outputFormat": "jpg",
    "safetyTolerance": 2,
    "promptUpsampling": False
}

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 action ID and input payload structure are defined to ensure seamless integration with the Cognitive Actions execution endpoint.

Conclusion

The black-forest-labs/flux-depth-pro actions empower developers to create visually stunning depth-aware images with ease. By leveraging the Generate Depth-Aware Images action, you can enrich your applications with captivating visuals that maintain spatial fidelity. Explore the possibilities this action offers, and consider diving deeper into additional use cases or integrating it into your existing projects to enhance user experience and engagement.

← Back to All Articles