Enhance Your Images with PuLID Cognitive Actions: A Developer's Guide

22 Apr 2025
Enhance Your Images with PuLID Cognitive Actions: A Developer's Guide

In the world of image processing, creating visually stunning and personalized images can be a daunting task. The PuLID Cognitive Actions provide a powerful API for developers to customize image identities, especially focusing on facial features, in text-to-image models. By leveraging these pre-built actions, you can achieve high identity similarity while modifying attributes, styles, and backgrounds, all while maintaining image consistency and accuracy.

Prerequisites

To get started with PuLID Cognitive Actions, you'll need an API key for the Cognitive Actions platform. This key should be included in the headers of your API requests for authentication. Keep in mind that the exact details of authentication may vary, but generally, you will need to include your API key in the request headers as a bearer token.

Cognitive Actions Overview

Customize Image Identity with PuLID

The Customize Image Identity with PuLID action allows you to enhance and customize image identities, particularly facial features, without altering the core functionality of the underlying model. This action is ideal for creating unique and personalized images while ensuring that the generated outputs remain true to the intended likeness.

Category: Image Processing

Input

The input for this action requires a JSON object with the following fields:

  • mainFaceImage (required): URL of the primary image representing the main identity.
  • seed (optional): Random seed for generation; leave blank for a randomized seed.
  • prompt (optional): Descriptive text guiding image generation. Default: "portrait,color,cinematic,in garden,soft light,detailed face".
  • cfgScale (optional): Guidance scale for image generation, recommended between 1 and 1.5. Default: 1.2.
  • imageWidth (optional): Width of the output image in pixels (range: 512-2024). Default: 768.
  • imageHeight (optional): Height of the output image in pixels (range: 512-2024). Default: 1024.
  • outputFormat (optional): Format of the output image. Options: webp, jpg, png. Default: webp.
  • identityScale (optional): Scale of identity influence (range: 0-5). Default: 0.8.
  • mixIdentities (optional): Enable to mix multiple identity images. Default: false.
  • numberOfSteps (optional): Number of step iterations for processing (range: 1-100). Default: 4.
  • outputQuality (optional): Quality level of the output image (0-100). Default: 80.
  • generationMode (optional): Mode for generation (fidelity or extremely style). Default: fidelity.
  • negativePrompt (optional): Terms to avoid during image generation, helping to exclude unwanted features.
  • numberOfSamples (optional): Number of image samples to generate (range: 1-8). Default: 4.
  • auxiliaryFaceImage1 (optional): Additional image for identity mixing, if enabled.
  • auxiliaryFaceImage2 (optional): Additional image for identity mixing, if enabled.
  • auxiliaryFaceImage3 (optional): Additional image for identity mixing, if enabled.

Example Input

{
  "prompt": "portrait, impressionist painting, loose brushwork, vibrant color, light and shadow play",
  "cfgScale": 1.2,
  "imageWidth": 768,
  "imageHeight": 1024,
  "outputFormat": "webp",
  "identityScale": 0.8,
  "mainFaceImage": "https://replicate.delivery/pbxt/Kr6iendsvYS0F3MLmwRZ8q07XIMEJdemnQI3Cmq9nNrauJbq/zcy.webp",
  "mixIdentities": false,
  "numberOfSteps": 4,
  "outputQuality": 80,
  "generationMode": "fidelity",
  "negativePrompt": "flaws in the eyes, flaws in the face, flaws, lowres, non-HDRi, low quality, worst quality,artifacts noise, text, watermark, glitch, deformed, mutated, ugly, disfigured, hands, low resolution, partially rendered objects,  deformed or partially rendered eyes, deformed, deformed eyeballs, cross-eyed,blurry",
  "numberOfSamples": 4
}

Output

The action typically returns an array of URLs pointing to the generated images based on the input specifications. Here's an example of what you might receive:

[
  "https://assets.cognitiveactions.com/invocations/eb53530e-4789-4233-8bc2-b2a4f5747f4f/f7513289-25ec-4b41-9865-454030460c4d.webp",
  "https://assets.cognitiveactions.com/invocations/eb53530e-4789-4233-8bc2-b2a4f5747f4f/5b6ecdc0-abc0-43c7-890e-cddb13572841.webp",
  "https://assets.cognitiveactions.com/invocations/eb53530e-4789-4233-8bc2-b2a4f5747f4f/4f1667ce-ae21-4da4-8089-3e12edd95530.webp",
  "https://assets.cognitiveactions.com/invocations/eb53530e-4789-4233-8bc2-b2a4f5747f4f/b4805293-bb46-4a46-9f7c-8447535dc40c.webp"
]

Conceptual Usage Example (Python)

Here’s a conceptual Python code snippet to illustrate how you might invoke the Customize Image Identity action using the PuLID API:

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 = "c02dd76b-b0e8-427c-ac46-7a7f704fd402"  # Action ID for Customize Image Identity with PuLID

# Construct the input payload based on the action's requirements
payload = {
    "prompt": "portrait, impressionist painting, loose brushwork, vibrant color, light and shadow play",
    "cfgScale": 1.2,
    "imageWidth": 768,
    "imageHeight": 1024,
    "outputFormat": "webp",
    "identityScale": 0.8,
    "mainFaceImage": "https://replicate.delivery/pbxt/Kr6iendsvYS0F3MLmwRZ8q07XIMEJdemnQI3Cmq9nNrauJbq/zcy.webp",
    "mixIdentities": False,
    "numberOfSteps": 4,
    "outputQuality": 80,
    "generationMode": "fidelity",
    "negativePrompt": "flaws in the eyes, flaws in the face, flaws, lowres, non-HDRi, low quality, worst quality,artifacts noise, text, watermark, glitch, deformed, mutated, ugly, disfigured, hands, low resolution, partially rendered objects,  deformed or partially rendered eyes, deformed, deformed eyeballs, cross-eyed,blurry",
    "numberOfSamples": 4
}

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, you replace the COGNITIVE_ACTIONS_API_KEY and the Cognitive Actions execution endpoint with your actual values. The payload variable is structured based on the action's required inputs, and the action ID is set to the correct value for customizing image identity.

Conclusion

The PuLID Cognitive Actions offer an innovative way to enhance and customize image identities in your applications, making it easier than ever to create stunning visuals that resonate with end-users. By following the guidelines in this article, you can effectively integrate these powerful actions into your projects, opening the door to a multitude of creative possibilities. Consider exploring additional use cases, such as blending identities or experimenting with different prompts, to unlock the full potential of the PuLID API. Happy coding!

← Back to All Articles