Customize Image Identity with PuLID for FLUX: A Developer's Guide to Cognitive Actions

22 Apr 2025
Customize Image Identity with PuLID for FLUX: A Developer's Guide to Cognitive Actions

In the world of image generation and customization, the zsxkib/flux-pulid API offers an innovative solution through its Cognitive Actions. Specifically, the action Customize Image Identity with PuLID for FLUX allows developers to create images that carry specific identities while preserving essential features. This powerful tool leverages advanced techniques like contrastive alignment and facial identity understanding, making it easier to generate consistent, high-similarity images tailored to your needs.

Prerequisites

Before you can start integrating the Cognitive Actions provided by the zsxkib/flux-pulid API, make sure you have:

  • An API key for the Cognitive Actions platform.
  • Basic knowledge of JSON and API requests.
  • A development environment set up with access to make HTTP requests.

Authentication typically involves passing your API key in the headers of your requests. This provides secure access to the Cognitive Actions.

Cognitive Actions Overview

Customize Image Identity with PuLID for FLUX

Description:
Utilize PuLID-FLUX-v0.9.0, a tuning-free solution optimized for FLUX.1-dev, allowing customization of images to add specific identities while retaining key features.

Category: image-generation

Input

The input for this action requires a structured JSON object. Below are the key fields:

  • mainFaceImage (required): URI of an ID image for face generation.
  • seed (optional): Specify a seed for random number generation.
  • width (optional): Width of the generated image in pixels (default: 896, range: 256-1536).
  • height (optional): Height of the generated image in pixels (default: 1152, range: 256-1536).
  • prompt (optional): Text prompt guiding the image generation (default: "portrait, color, cinematic").
  • trueCfg (optional): Classifier-Free Guidance scale (default: 1, range: 1-10).
  • idWeight (optional): Influence weight of the ID image (default: 1, range: 0-3).
  • startStep (optional): Step number for ID insertion (default: 0, range: 0-4).
  • outputFormat (optional): Desired output format (default: "webp", options: png, jpg, webp).
  • guidanceScale (optional): Scale of the text prompt's influence (default: 4, range: 1-10).
  • numberOfSteps (optional): Total denoising steps (default: 20, range: 1-20).
  • outputQuality (optional): Quality level for output images (default: 80, range: 1-100).
  • negativePrompt (optional): Elements to avoid in the generated image.
  • numberOfOutputs (optional): Count of images to generate (default: 1, range: 1-4).
  • maxSequenceLength (optional): Maximum prompt sequence length (default: 128, range: 128-512).

Example Input:

{
  "width": 896,
  "height": 1152,
  "prompt": "a woman holding sign with glowing green text \"PuLID for FLUX\"",
  "trueCfg": 1,
  "idWeight": 1,
  "startStep": 4,
  "outputFormat": "webp",
  "guidanceScale": 4,
  "mainFaceImage": "https://yanze-pulid.hf.space/--replicas/g5yty/file=/tmp/gradio/7567beceda2541f726af7beb4c9aa857b4a96b77/liuyifei.png",
  "numberOfSteps": 20,
  "outputQuality": 80,
  "negativePrompt": "bad quality, worst quality, text, signature, watermark, extra limbs",
  "numberOfOutputs": 4,
  "maxSequenceLength": 128
}

Output

The output of this action typically returns an array of URIs pointing to the generated images. Here’s what you might expect:

Example Output:

[
  "https://assets.cognitiveactions.com/invocations/52694391-a71f-4421-ac6f-b1bebfede081/8bff7536-a128-4b24-874a-e8926f39fdb1.webp",
  "https://assets.cognitiveactions.com/invocations/52694391-a71f-4421-ac6f-b1bebfede081/369f3f0d-8be8-4114-9a43-2a5fc00ea6ae.webp",
  "https://assets.cognitiveactions.com/invocations/52694391-a71f-4421-ac6f-b1bebfede081/b90c0377-8a50-408d-b3be-b5024e042858.webp",
  "https://assets.cognitiveactions.com/invocations/52694391-a71f-4421-ac6f-b1bebfede081/7ffed10c-0c6a-4ee0-8d00-b8d07c9d52dd.webp"
]

Conceptual Usage Example (Python)

Here’s how you might structure a request to call this 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 = "916fbb26-6b83-4955-b499-5190ec2ab707" # Action ID for Customize Image Identity with PuLID for FLUX

# Construct the input payload based on the action's requirements
payload = {
    "width": 896,
    "height": 1152,
    "prompt": "a woman holding sign with glowing green text \"PuLID for FLUX\"",
    "trueCfg": 1,
    "idWeight": 1,
    "startStep": 4,
    "outputFormat": "webp",
    "guidanceScale": 4,
    "mainFaceImage": "https://yanze-pulid.hf.space/--replicas/g5yty/file=/tmp/gradio/7567beceda2541f726af7beb4c9aa857b4a96b77/liuyifei.png",
    "numberOfSteps": 20,
    "outputQuality": 80,
    "negativePrompt": "bad quality, worst quality, text, signature, watermark, extra limbs",
    "numberOfOutputs": 4,
    "maxSequenceLength": 128
}

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 the placeholder for the API key and ensure the action ID and input payload are structured correctly. The endpoint URL and request structure shown are illustrative and should be modified according to your specific integration needs.

Conclusion

The Customize Image Identity with PuLID for FLUX action offers a powerful way to generate customized images while maintaining fidelity to the original identity features. By leveraging its capabilities, developers can create diverse applications ranging from personalized media content to interactive experiences. Start integrating this Cognitive Action today to unlock endless possibilities in image generation!

← Back to All Articles