# AI Influencer

> Create one AI influencer character sheet. Human and animal modes. $0.05 per sheet.

## Overview

- **Endpoint**: `https://api.higgsfield.ai/higgsfield/ai-influencer`
- **Model ID**: `higgsfield/ai-influencer`
- **Category**: image_edit, text2image
- **Kind**: inference
- **Tags**: featured, trending

## Pricing

Public pricing information is not available for this model.

## Authentication

Keep credentials in server-side environment variables. The SDKs accept the same `KEY_ID:KEY_SECRET` value under their documented variable names.

```bash
export HF_CREDENTIALS="YOUR_KEY_ID:YOUR_KEY_SECRET" # TypeScript
export HF_KEY="YOUR_KEY_ID:YOUR_KEY_SECRET"         # Python and cURL
```

The official SDKs configure the authorization header. Keep credentials server-side; the TypeScript SDK blocks browser use.

## API Information

Use `subscribe` to submit the model request and wait for a terminal result. TypeScript performs automatic polling with `withPolling: true`; Python's synchronous `subscribe` call also waits.

### Input Parameters

- **`seed`** (`['integer', 'null']`, _optional_):
  - Default: `null`

- **`tier`** (`string`, _optional_):
  - Default: `"normal"`
  - Options: `normal`, `freak`, `total`, `insects`, `frogs`, `cats`, `dogs`, `capybaras`, `birds`

- **`brief`** (`string`, _optional_):
  - Default: `""`

- **`image_url`** (`['string', 'null']`, _optional_):
  - Default: `null`

- **`selection`** (`object`, _optional_):
  - Default: `{}`

- **`body_color`** (`['string', 'null']`, _optional_):

- **`pinned_species`** (`['string', 'null']`, _optional_):

- **`trait_variants`** (`any`, _optional_):
  - Default: `null`

- **`item_image_urls`** (`list<string>`, _optional_):
  - Default: `[]`

- **`variation_index`** (`integer`, _optional_):
  - Default: `0`

### Input JSON Schema

```json
{
  "type": "object",
  "$defs": {
    "TraitVariants": {
      "type": "object",
      "title": "TraitVariants",
      "required": [
        "version",
        "choices"
      ],
      "properties": {
        "choices": {
          "type": "object",
          "title": "Choices",
          "properties": {
            "pr_centaur": {
              "enum": [
                "v1",
                "v2",
                "v3",
                "v4",
                "v5",
                "v6",
                "v7",
                "v8",
                "v9",
                "v10"
              ]
            }
          },
          "maxProperties": 512,
          "additionalProperties": {
            "enum": [
              "original",
              "v1",
              "v2",
              "v3",
              "v4",
              "v5"
            ],
            "type": "string"
          }
        },
        "version": {
          "type": "string",
          "const": "appearance-v2",
          "title": "Version"
        },
        "animal_choices": {
          "anyOf": [
            {
              "type": "object",
              "maxProperties": 64,
              "additionalProperties": {
                "type": "integer",
                "maximum": 4,
                "minimum": 0
              }
            },
            {
              "type": "null"
            }
          ],
          "title": "Animal Choices",
          "default": null
        }
      },
      "additionalProperties": false
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "tier": {
            "enum": [
              "normal",
              "freak",
              "total"
            ]
          }
        }
      },
      "then": {
        "properties": {
          "body_color": {
            "type": "null"
          },
          "pinned_species": {
            "type": "null"
          },
          "trait_variants": {
            "properties": {
              "animal_choices": {
                "type": "null"
              }
            }
          },
          "variation_index": {
            "const": 0
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "tier": {
            "not": {
              "const": "insects"
            }
          }
        }
      },
      "then": {
        "properties": {
          "pinned_species": {
            "type": "null"
          }
        }
      }
    }
  ],
  "title": "AI Influencer input",
  "properties": {
    "seed": {
      "type": [
        "integer",
        "null"
      ],
      "default": null,
      "maximum": 1000000,
      "minimum": 1
    },
    "tier": {
      "enum": [
        "normal",
        "freak",
        "total",
        "insects",
        "frogs",
        "cats",
        "dogs",
        "capybaras",
        "birds"
      ],
      "type": "string",
      "default": "normal"
    },
    "brief": {
      "type": "string",
      "title": "",
      "default": "",
      "maxLength": 4000
    },
    "image_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "default": null,
      "maxLength": 2083,
      "minLength": 1
    },
    "selection": {
      "type": "object",
      "default": {},
      "maxProperties": 18,
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "body_color": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^#[0-9a-fA-F]{6}$"
    },
    "pinned_species": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 64,
      "minLength": 1
    },
    "trait_variants": {
      "anyOf": [
        {
          "$ref": "#/$defs/TraitVariants"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "item_image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "maxLength": 2083,
        "minLength": 1
      },
      "default": [],
      "maxItems": 3
    },
    "variation_index": {
      "type": "integer",
      "default": 0,
      "maximum": 2147483647,
      "minimum": 0
    }
  },
  "additionalProperties": false
}
```

### Required Parameters Example

```json
{
  "seed": null,
  "tier": "normal",
  "brief": "",
  "image_url": null,
  "selection": {},
  "trait_variants": null,
  "item_image_urls": [],
  "variation_index": 0
}
```

### Output Schema

The shared polling endpoint returns one of the following status shapes:

```json
{
  "title": "RequestStatus",
  "oneOf": [
    {
      "title": "PendingRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "in_progress",
            "nsfw",
            "canceled"
          ]
        }
      },
      "required": [
        "status",
        "request_id"
      ]
    },
    {
      "title": "FailedRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "const": "failed"
        },
        "error": {
          "type": "string"
        }
      },
      "required": [
        "status",
        "request_id",
        "error"
      ]
    },
    {
      "title": "CompletedRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "const": "completed"
        },
        "images": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "url"
            ]
          }
        }
      },
      "required": [
        "status",
        "request_id",
        "images"
      ]
    }
  ]
}
```

## SDK Installation

Install one of the official server-side SDKs:

```bash
npm install @higgsfield/client
# or
pip install higgsfield-client
```

## Usage Examples

### TypeScript

```typescript
import { config, higgsfield } from "@higgsfield/client/v2";

config({
  credentials: process.env.HF_CREDENTIALS,
});

const result = await higgsfield.subscribe(
  "higgsfield/ai-influencer",
  {
    input: {
      "seed": null,
      "tier": "normal",
      "brief": "",
      "image_url": null,
      "selection": {},
      "trait_variants": null,
      "item_image_urls": [],
      "variation_index": 0
    },
    withPolling: true,
  },
);

console.log(result);
```

### Python

```python
import higgsfield_client

result = higgsfield_client.subscribe(
    'higgsfield/ai-influencer',
    arguments={'seed': None,
         'tier': 'normal',
         'brief': '',
         'image_url': None,
         'selection': {},
         'trait_variants': None,
         'item_image_urls': [],
         'variation_index': 0},
)

print(result)
```

### cURL

```bash
curl --request POST \
  --url 'https://api.higgsfield.ai/higgsfield/ai-influencer' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "seed": null,
  "tier": "normal",
  "brief": "",
  "image_url": null,
  "selection": {},
  "trait_variants": null,
  "item_image_urls": [],
  "variation_index": 0
}
JSON
```

## Additional Documentation

# AI Influencer

Create a character reference sheet with a close-up portrait and a full-body view. Choose a human or animal character, customize its appearance, and optionally supply an identity photo and clothing or item references.

Each request produces **one 2K image at 16:9**, with Medium quality. The price is **$0.05 per sheet** for every character type, before any account-specific discounts. Resolution, aspect ratio and quality are fixed.

## Quick start

Send a JSON request to `POST https://api.higgsfield.ai/higgsfield/ai-influencer` with your API key:

```bash
curl --request POST 'https://api.higgsfield.ai/higgsfield/ai-influencer' \
  --header "Authorization: Key ${HF_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"tier":"normal","selection":{"gender":["female"],"body_type":["body_athletic"],"height":["h_tall"]},"seed":42817}'
```

Set `HF_API_KEY` to your `key-id:secret`. All input fields are optional; the default character type is `normal`.

Generation is asynchronous. The response includes `request_id`, `status`, `status_url` and `cancel_url`. Poll the returned `status_url` with the same authorization header. When `status` is `completed`, the generated sheet is available at `images[0].url`.

## Character types

| `tier` | Playground label | Character |
| --- | --- | --- |
| `normal` | Average | Human with natural appearance; default |
| `freak` | Bold | Human with more unusual appearance traits |
| `total` | Extreme | Human with stronger appearance transformations |
| `insects` | Insect | Insect character |
| `frogs` | Frog | Frog character |
| `cats` | Cat | Cat character |
| `dogs` | Dog | Dog character |
| `capybaras` | Rodent | Capybara character |
| `birds` | Bird | Bird character |

Use the API values in the first column, not the display labels.

## Inputs

| Parameter | Type / default | Usage |
| --- | --- | --- |
| `tier` | string, `"normal"` | One of the nine character types above. |
| `selection` | object, `{}` | Category keys mapped to arrays of option keys. Up to 18 categories; each category has its own selection limit. Discover current keys through the options endpoint below. |
| `image_url` | URL or null, `null` | One identity reference photo. This is separate from item references. |
| `item_image_urls` | URL array, `[]` | Up to three clothing, footwear or item references, in order. |
| `brief` | string, `""` | Optional character direction, up to 4,000 characters. Supported by the API even though hidden in the playground form. |
| `seed` | integer or null, `null` | Character-selection seed from 1 to 1,000,000. Omit it for an automatically generated seed. |
| `variation_index` | integer, `0` | Animal sequence position from 0 to 2,147,483,647. Human types require `0`. |
| `body_color` | string or null | Optional animal body color as `#RRGGBB`. Human types require omission or null. |
| `pinned_species` | string or null | Optional valid insect species ID, 1–64 characters, to keep the species fixed while varying its look. Only supported with `tier="insects"`. Unknown IDs are rejected. |
| `trait_variants` | object or null, `null` | Advanced overrides for selected appearance traits; normally omit this field. See below. |

Image URLs must be reachable by the API and point to non-animated JPEG, PNG or WebP files. The download limit is 64 MiB per image; images must also pass decoding and image validation. Upload local files first and pass their URLs, rather than file objects or base64 data.

### Identity photo and item references

`image_url` is the **Upload your photo** field. `item_image_urls` is **Add elements or references**. The identity photo does not count toward the three-item limit.

```json
{
  "tier": "normal",
  "image_url": "https://example.com/identity.jpg",
  "item_image_urls": [
    "https://example.com/jacket.png",
    "https://example.com/shoes.png"
  ],
  "seed": 42817
}
```

Replace these example URLs with your uploaded images. The identity reference guides the character's likeness; item references guide clothing or other items.

## Appearance options

Fetch `GET https://api.higgsfield.ai/models/higgsfield/ai-influencer/options` to discover the current catalog. This endpoint does not require authentication when the model is visible and publicly available; it returns `404` while the model is hidden or unavailable in the public catalog. Generation always requires authentication and model access.

The response contains `config_revision` and `categories`. Each category provides `key`, `label`, `tiers`, `max` and `options`. Each option provides `key`, `label`, nullable `img`, nullable `color`, nullable `tiers`, nullable `slot` and `exclusive`.

To build a selection:

1. Keep categories whose `tiers` include the selected character type. Human and animal categories can share a key; choose the matching tier's category.
2. If an option has a non-null `tiers` list, show it only for those types.
3. Send category and option **keys** in `selection`, with at most `max` options per category. Select at most one option for each non-null facial `slot`. An `exclusive` option must be selected alone in its category.
4. Use `img` for previews, `color` for color swatches, and labels when no visual is provided. A null preview does not mean the option is invalid. Preserve catalog order and refresh cached choices when `config_revision` changes.

For example:

```json
{
  "tier": "normal",
  "selection": {
    "gender": ["female"],
    "body_type": ["body_athletic"],
    "height": ["h_tall"]
  }
}
```

The catalog includes human settings such as gender, ethnicity, age, skin tone, height, body type, proportions, eyes, hair, distinctive features, style and accessories. Available options depend on the character type. Rebuild or filter selections when switching between human and animal types; stale or incompatible keys are rejected.

## Animal variations

Keep `seed` and `tier` fixed and increment `variation_index` for successive animal selections:

```json
{
  "tier": "cats",
  "seed": 42817,
  "variation_index": 0,
  "body_color": "#D9A066"
}
```

Use index `1` for the next request, then `2`, and so on. Species cycle through the available set without repeats within a cycle, while appearance components vary independently. Explicit selections and trait overrides can constrain the variation; pinning an insect species keeps that species fixed.

The seed controls character selection, not exact output pixels. Repeating a seed and index does not guarantee an identical rendered image, and catalog changes can affect future selections. An automatically generated seed is not returned as additional response metadata; supply and store your own seed when you need a sequence. Use the standard `Idempotency-Key` header to deduplicate retries, with a new key for each new variation.

## Advanced trait overrides

When supplying `trait_variants`, include `"version": "appearance-v2"` and a `choices` object mapping eligible selected trait keys to their supported variant IDs. General variants are `original` and `v1`–`v5`; the current schema additionally permits `v1`–`v10` for `pr_centaur`. Variants must be supported by the current trait catalog.

For animals, optional `animal_choices` maps eligible selected animal option keys to integer indices `0`–`4`. This field must be omitted or null for human types. Unspecified eligible traits use their original/default variant when an override object is supplied. The public options endpoint does not expose the internal trait-variant or insect-species catalogs; omit these advanced overrides unless you already have valid identifiers.

## Additional Resources

- [Model page](https://console.higgsfield.ai/models/higgsfield/ai-influencer)
- [This LLM-readable document](https://dash.higgsfield.ai/models/higgsfield/ai-influencer/llms.txt)