Soul ID — Create character API - Higgsfield API Docs

← Soul ID Endpoint: POST https://api.higgsfield.ai/v1/custom-references Catalog ID: soul-id

Usage notes

Soul ID trains a reusable character reference. This is not an image-generation endpoint; do not POST to /soul-id.
Use POST /v1/custom-references with application/json. name has a maximum length of 100; input_images must contain 1–100 {“type”:“image_url”,“image_url”:”…”} objects.
model_version accepts v1, v2, cinema; its default is v1. Choose the matching generation family.
The creation response returns id and status. Poll GET /v1/custom-references/{id}; statuses are not_ready, queued, in_progress, completed, and failed.
After completion, pass the returned id as custom_reference_id to the matching Soul generation endpoint. References are scoped to the account that created them.

Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

cURL

curl --request POST \
  --url https://api.higgsfield.ai/v1/custom-references \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "My character",
  "model_version": "v2",
  "input_images": [
    {
      "type": "image_url",
      "image_url": "https://example.com/portrait-front.jpg"
    },
    {
      "type": "image_url",
      "image_url": "https://example.com/portrait-side.jpg"
    },
    {
      "type": "image_url",
      "image_url": "https://example.com/portrait-outdoors.jpg"
    }
  ]
}'

Input schema

string

required

Name of the character reference. Maximum characters: 100.

string

default:"v1"

SOUL family that will use this character reference. Allowed values: "v1", "v2", "cinema".

array

required

Training images supplied as public URL objects. Minimum items: 1. Maximum items: 100.

Show Nested fields

string

required

Must be "image_url".

string

required

Public URL of the input image. Minimum characters: 1. Maximum characters: 2083. Format: uri.

Complete JSON schema

{
  "$defs": {
    "ImageUrlInputImageSchema": {
      "properties": {
        "type": {
          "const": "image_url",
          "title": "Type",
          "type": "string"
        },
        "image_url": {
          "format": "uri",
          "maxLength": 2083,
          "minLength": 1,
          "title": "Image Url",
          "type": "string"
        }
      },
      "required": [
        "type",
        "image_url"
      ],
      "title": "ImageUrlInputImageSchema",
      "type": "object"
    },
    "SoulModelVersion": {
      "enum": [
        "v1",
        "v2",
        "cinema"
      ],
      "title": "SoulModelVersion",
      "type": "string"
    }
  },
  "properties": {
    "name": {
      "maxLength": 100,
      "title": "Name",
      "type": "string"
    },
    "model_version": {
      "$ref": "#/$defs/SoulModelVersion",
      "default": "v1"
    },
    "input_images": {
      "items": {
        "$ref": "#/$defs/ImageUrlInputImageSchema"
      },
      "maxItems": 100,
      "minItems": 1,
      "title": "Input Images",
      "type": "array"
    }
  },
  "required": [
    "name",
    "input_images"
  ],
  "title": "CreateCustomReferenceSchema",
  "type": "object"
}

Response

The response is a character reference with id, name, model_version, status, thumbnail_url, created_at, in_progress_at and fail_reason. Poll GET https://api.higgsfield.ai/v1/custom-references/{id} with the same API credentials. Training states are not_ready, queued, in_progress, completed and failed. After completed, pass the reference id as custom_reference_id to the matching SOUL generation workflow. The reference must belong to your account. Training does not return request_id or generated images.

Get started

Model API reference

Core concepts

SDKs

Organizations

API reference

Resources

Soul ID — Create character API

Usage notes

Quick start

Input schema

Response

​Usage notes

​Quick start

​Input schema

​Response

Usage notes

Quick start

Input schema

Response