Higgsfield Soul 2 custom_reference_id is not a Sume parameter

Higgsfield's own Soul 2 API accepts a custom_reference_id, but Sume's Soul does not: on Sume, higgsfield/soul is text-to-image only, takes no reference images, and has no pass-through for provider-specific fields. If you want the same character across a set of Sume images, use a model whose catalog row accepts input_references, or build a reusable Avatar.

The distinction matters because a saved character reference is the feature people usually mean by Soul consistency. It exists on Higgsfield's side. It is not exposed on Sume's, and I could not find any code on origin/main that sends it.

What Higgsfield documents

The Soul 2 parameters page lists aspect_ratio values of 9:16, 16:9, 4:3, 3:4, 1:1, 2:3 and 3:2, a resolution of 720p or 1080p with 720p as the default, and a batch size of 1 or 4. It also lists custom_reference_id, a UUID for a completed character reference owned by your account, and custom_reference_strength, a number between 0 and 1. The page adds that the current runtime cannot process a strength of 0 even though the schema accepts it, so the value has to be above zero when you use a reference.

What Sume exposes for Soul

Sume's Soul row carries the same ratios, the same two resolutions and the same batch of 1 or 4. Its catalog constraint reads text-to-image only, and the request validator rejects quality, image_size, rendering_speed, output_format, format and mask fields for Soul. The Image API docs add that allowed_passthrough_parameters is empty for every endpoint in v1 and that provider.options must be omitted or empty, so there is no field to carry a character id through.

A request that sets a parameter the model does not list returns 400 unsupported_parameter, so a stray custom_reference_id fails loudly instead of being silently dropped.

Where consistency lives on Sume

For stills, pick a model with reference slots. Sume's docs state 16 references for ChatGPT Image 2.5, 5 for Ideogram 4.5 (one image to edit and up to four references), and a shared ceiling of 10 for the other edit-capable models. The script below prints the real number per model from the catalog so you do not depend on this page.

For a presenter who has to appear in video as well, Sume's Avatar 1.0 route creates a reusable avatar from a prompt, a profile or a reference image and gives you a handle you reuse in avatar videos. That is the Sume equivalent of a saved character, but it is a separate product from the Image API.

A practical order of work: decide whether the character must appear in video, pick the still model by its reference ceiling, and put the same reference images in the same order in every request of the set. Sume's docs say reference URLs must be public HTTPS, so host the character sheet somewhere fetchable first. None of this reproduces a saved Soul character, but it keeps the identity anchored to pixels you control.

import os
import requests

H = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"]}
r = requests.get("https://api.sume.com/v1/images/models", headers=H, timeout=30)
for m in r.json()["data"]:
    refs = m["supported_parameters"].get("input_references", {})
    print(m["id"], refs.get("max", 0))