Create Stunning Personalized Headshots with visoar/headshots.fun Cognitive Actions

25 Apr 2025
Create Stunning Personalized Headshots with visoar/headshots.fun Cognitive Actions

In today's digital world, personalized images and avatars are essential for branding, identity, and user engagement. The visoar/headshots.fun Cognitive Actions offer developers a powerful tool to generate unique headshot images tailored to specific styles and settings. With the ability to customize various parameters like image size, quality, and artistic style, these actions simplify the process of creating professional and appealing portraits.

Prerequisites

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

  • An API key for the Cognitive Actions platform.
  • Basic understanding of JSON and RESTful API concepts.

Authentication can typically be handled by passing your API key in the headers of your requests, allowing you to securely access the action functionalities.

Cognitive Actions Overview

Generate Headshot Images

Description:
This action enables the creation of personalized headshot images using the bytedance-puild model. You can customize the generated images through various parameters, making it ideal for producing unique portraits.

Category: Image Generation

Input

The input for this action requires the following fields:

  • primaryFaceImage (string, required): URL of the main face image to be used in generation.
  • mode (string, optional): Generation mode, can be "fidelity" (prioritizes accuracy) or "extremely style" (emphasizes artistic expression). Default is "fidelity".
  • format (string, optional): The output format for the image, options include "webp", "jpg", and "png". Default is "png".
  • prompt (string, optional): A guiding text prompt for image generation, defaults to "portrait,color,cinematic,in garden,soft light,detailed face".
  • imageWidth (integer, optional): Width of the output image in pixels, must be between 512 and 2024. Default is 768.
  • imageHeight (integer, optional): Height of the output image in pixels, must be between 512 and 2024. Default is 1024.
  • numberOfSteps (integer, optional): Number of processing steps for detail, ranging from 1 to 100. Default is 4.
  • outputQuality (integer, optional): Quality of the output image, ranging from 0 (lowest) to 100 (highest). Default is 80.
  • avoidancePrompt (string, optional): Defines unwanted features to avoid in the image.
  • numberOfSamples (integer, optional): Number of image variations to produce, between 1 and 8. Default is 1.
  • allowIdentityMix (boolean, optional): Enable mixing of two identity images. Default is false.
  • secondaryFaceImage1 (string, optional): URL for the first auxiliary face image.
  • secondaryFaceImage2 (string, optional): URL for the second auxiliary face image.
  • secondaryFaceImage3 (string, optional): URL for the third auxiliary face image.
  • controlGuidanceScale (number, optional): Guidance scale during generation, recommended range is 1 to 1.5. Default is 1.2.
  • identityMatchingScale (number, optional): Scale for matching identities, ranging from 0 to 5. Default is 0.8.

Example Input:

{
  "mode": "fidelity",
  "format": "png",
  "prompt": "headshot",
  "imageWidth": 768,
  "imageHeight": 1024,
  "numberOfSteps": 4,
  "outputQuality": 80,
  "avoidancePrompt": "flaws in the eyes, flaws in the face, flaws...",
  "numberOfSamples": 1,
  "allowIdentityMix": false,
  "primaryFaceImage": "https://replicate.delivery/pbxt/Llj0TSTdW1D7Ebjd7PgYw7VsKzVL9i8KbZpeok6iO0II8Zsj/A_beautiful_blond_goddess_girl%2C_fantasy%2Cportrait%2C_-512x512_10steps_seed_9207.jpg",
  "controlGuidanceScale": 1.2,
  "identityMatchingScale": 0.8
}

Output

The action typically returns a URL to the generated headshot image.

Example Output:

[
  "https://assets.cognitiveactions.com/invocations/950aee17-c947-4ec1-93c2-50ccaf0c4eb0/2a3ad6bd-a4c5-47fd-a557-953b2e4c1cd2.png"
]

Conceptual Usage Example (Python)

Here’s how you might call the Generate Headshot 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 = "16f5c464-ada6-455e-937b-9f1210ee84d9" # Action ID for Generate Headshot Images

# Construct the input payload based on the action's requirements
payload = {
    "mode": "fidelity",
    "format": "png",
    "prompt": "headshot",
    "imageWidth": 768,
    "imageHeight": 1024,
    "numberOfSteps": 4,
    "outputQuality": 80,
    "avoidancePrompt": "flaws in the eyes, flaws in the face, flaws...",
    "numberOfSamples": 1,
    "allowIdentityMix": false,
    "primaryFaceImage": "https://replicate.delivery/pbxt/Llj0TSTdW1D7Ebjd7PgYw7VsKzVL9i8KbZpeok6iO0II8Zsj/A_beautiful_blond_goddess_girl%2C_fantasy%2Cportrait%2C_-512x512_10steps_seed_9207.jpg",
    "controlGuidanceScale": 1.2,
    "identityMatchingScale": 0.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}
    )
    response.raise_for_status()

    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, the action ID and input payload are structured according to the action's requirements. The endpoint URL and request structure are illustrative, showcasing how you can interact with the Cognitive Actions API.

Conclusion

The visoar/headshots.fun Cognitive Actions provide a robust solution for generating customized headshot images. With a variety of parameters to tweak, developers can create highly personalized images that cater to their specific needs. Whether you are building applications that require unique user avatars or simply wish to enhance your digital presence, these actions offer a straightforward way to elevate your image generation capabilities. Start exploring the possibilities today!

← Back to All Articles