Enhance Portrait Images with Cognitive Actions: A Guide to Ultimate Upscaling

25 Apr 2025
Enhance Portrait Images with Cognitive Actions: A Guide to Ultimate Upscaling

In the world of digital imaging, enhancing the resolution and quality of portraits can significantly impact visual applications. The juergengunz/ultimate-portrait-upscale API offers a powerful Cognitive Action designed specifically for this purpose. Through its Upscale Portrait Images with ControlNet action, developers can leverage advanced technological capabilities to improve the quality of portrait images using customizable settings. This blog post will guide you through the integration of this action into your applications, highlighting its features and use cases.

Prerequisites

Before you start using the Cognitive Actions, ensure you have the following:

  • An API key for the Cognitive Actions platform to authenticate your requests.
  • Familiarity with JSON payload structures since you'll be sending and receiving data in this format.
  • Understanding of image formats and URIs to work effectively with the input and output of the image processing.

Authentication typically involves passing your API key in the headers of your requests.

Cognitive Actions Overview

Upscale Portrait Images with ControlNet

The Upscale Portrait Images with ControlNet action enhances the resolution of portrait images using ControlNet Tile technology. This action allows for improved quality through various customizable settings, including denoise levels, upscaling methods, and sampling strategies, ensuring photorealistic outcomes.

Input

The input for this action requires a JSON object with several fields, of which the image URI is mandatory. Here’s a breakdown:

  • image: string (required) - A URI pointing to the input image file.
  • seed: integer (optional) - Initializes the random number generator for sampling; leave empty for a random seed.
  • steps: integer (optional, default: 20) - Number of steps for processing.
  • maskBlur: integer (optional, default: 8) - Blur applied to mask edges.
  • scheduler: string (optional, default: "normal") - Strategy used for processing.
  • tileWidth: integer (optional, default: 512) - Width of each tile in pixels.
  • tileHeight: integer (optional, default: 512) - Height of each tile in pixels.
  • tilePadding: integer (optional, default: 32) - Padding size around each tile in pixels.
  • blendingMode: string (optional, default: "Linear") - Blending method used between tiles.
  • denoiseFactor: number (optional, default: 0.1) - Amount of denoising to apply.
  • negativePrompt: string (optional, default: "cartoon, cgi, render, painting, illustration, drawing") - Elements to avoid.
  • positivePrompt: string (optional, default: "business portrait, detailed skin, perfect skin, soft lighting, beautiful eyes, photorealistic, perfect teeth") - Desired elements in the output.
  • upscalingMethod: string (optional, default: "4x-UltraSharp") - Method used to upscale images.
  • sampleMethodName: string (optional, default: "euler") - Method used for sampling.
  • forceUniformTiles: boolean (optional, default: true) - Ensures all tiles have uniform dimensions.
  • upscaleMultiplier: number (optional, default: 2) - Factor by which image dimensions are increased.
  • configurationValue: number (optional, default: 8) - Controls the configuration value for the model.
  • seamCorrectionMode: string (optional, default: "None") - Mode used to correct seams between tiles.
  • seamCorrectionWidth: integer (optional, default: 64) - Width used for seam correction.
  • seamCorrectionDenoise: number (optional, default: 1) - Denoise factor used in seam correction.
  • seamCorrectionPadding: integer (optional, default: 16) - Padding for seam correction.
  • useControlNetworkTile: boolean (optional, default: true) - Uses the ControlNet tile for processing.
  • controlNetworkStrength: number (optional, default: 1) - Strength of the ControlNet influence.
  • seamCorrectionMaskBlur: integer (optional, default: 8) - Blur applied during seam correction.

Example Input:

{
  "image": "https://replicate.delivery/pbxt/K1jy8x3lgsayBRp1SwKmFoQrFGoEOvQ56VcwGIHM6giTiyPm/test.png",
  "steps": 20,
  "maskBlur": 8,
  "scheduler": "normal",
  "tileWidth": 512,
  "tileHeight": 512,
  "tilePadding": 32,
  "blendingMode": "Linear",
  "denoiseFactor": 0.1,
  "negativePrompt": "cartoon, cgi, render, painting, illustration, drawing",
  "positivePrompt": "business portrait of a man, detailed skin, perfect skin, soft lighting, beautiful blue eyes, photorealistic",
  "upscalingMethod": "4x-UltraSharp",
  "sampleMethodName": "euler",
  "forceUniformTiles": true,
  "upscaleMultiplier": 2,
  "configurationValue": 8,
  "seamCorrectionMode": "None",
  "seamCorrectionWidth": 64,
  "seamCorrectionDenoise": 1,
  "seamCorrectionPadding": 16,
  "useControlNetworkTile": true,
  "controlNetworkStrength": 1,
  "seamCorrectionMaskBlur": 8
}

Output

The action typically returns a URL to the enhanced image, which can be used to display the processed result.

Example Output:

https://assets.cognitiveactions.com/invocations/a0fadc14-3802-4b27-a155-b6da30f27191/4dc793a6-2e92-4733-bc18-f4110aef24d2.png

Conceptual Usage Example (Python)

Here’s how you would call the Upscale Portrait Images with ControlNet 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 = "df0f9fb3-ebd6-4e55-a3cb-7fe18e990e33" # Action ID for Upscale Portrait Images with ControlNet

# Construct the input payload based on the action's requirements
payload = {
    "image": "https://replicate.delivery/pbxt/K1jy8x3lgsayBRp1SwKmFoQrFGoEOvQ56VcwGIHM6giTiyPm/test.png",
    "steps": 20,
    "maskBlur": 8,
    "scheduler": "normal",
    "tileWidth": 512,
    "tileHeight": 512,
    "tilePadding": 32,
    "blendingMode": "Linear",
    "denoiseFactor": 0.1,
    "negativePrompt": "cartoon, cgi, render, painting, illustration, drawing",
    "positivePrompt": "business portrait of a man, detailed skin, perfect skin, soft lighting, beautiful blue eyes, photorealistic",
    "upscalingMethod": "4x-UltraSharp",
    "sampleMethodName": "euler",
    "forceUniformTiles": True,
    "upscaleMultiplier": 2,
    "configurationValue": 8,
    "seamCorrectionMode": "None",
    "seamCorrectionWidth": 64,
    "seamCorrectionDenoise": 1,
    "seamCorrectionPadding": 16,
    "useControlNetworkTile": True,
    "controlNetworkStrength": 1,
    "seamCorrectionMaskBlur": 8
}

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 Python snippet:

  • Replace YOUR_COGNITIVE_ACTIONS_API_KEY with your actual API key.
  • Adjust the endpoint URL as necessary.
  • The payload is structured according to the required input schema.

Conclusion

The Upscale Portrait Images with ControlNet action provides developers with an efficient way to enhance portrait images, ensuring high-quality results with customizable settings. By integrating this action into your applications, you can significantly improve the visual appeal of your portrait images. Consider exploring other use cases and potential enhancements to fully leverage the capabilities of the juergengunz/ultimate-portrait-upscale API. Happy coding!

← Back to All Articles