Higgsfield Soul on Sume: n must be 1 or 4, n=2 and n=3 return 400

Higgsfield Soul on Sume takes n of 1 or 4 and nothing in between, so a request for 2 or 3 images fails with 400 invalid_request and the message n must be 1 or 4 for higgsfield/soul. The row is the cheapest in the catalog at $0.005 per image at 720p and $0.0075 at 1080p, takes no reference images and rejects image_size.

The rule is in the generation code on origin/main and the row is described in the Image API docs. Everything below is from those two sources, read on 2026-10-10.

The row at a glance

Soul lists seven aspect ratios and a resolution field with two values, 720p and 1080p. Its input_references descriptor has a maximum of 0, so it is text-only: you cannot edit a photo with it. Nano Banana, GPT Image, Seedream, FLUX and Qwen rows are where references live.

What a batch costs

Four images at 720p cost 4 x $0.005 = $0.02. Four at 1080p cost 4 x $0.0075 = $0.03. A hundred four-image calls at 1080p, 400 images in all, cost $3.00.

If you only need two images, send n: 4 and use two, or send two calls with n: 1. Sending n: 4 costs $0.015 more at 1080p than two single calls, but it is one request. Sending two single calls is cheaper at $0.015 total but is two requests. Choose by whether the cost or the latency matters to you.

A request that works

Use resolution instead of image_size, and aspect_ratio for the shape. The snippet below sends one call with four 1080p images. It checks the status code, because a slow call may return 202 with a job envelope instead of a finished body.

import json, os, urllib.request

body = {
    "model": "higgsfield/soul",
    "prompt": "a calm street at dawn, film grain",
    "n": 4,
    "aspect_ratio": "9:16",
    "resolution": "1080p",
}
req = urllib.request.Request(
    "https://api.sume.com/v1/images",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["SUME_API_KEY"],
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(req, timeout=60) as r:
    print(r.status, list(json.load(r)))

Other things to remember

Because Soul is text-only, any call that includes input_references fails. If a workflow needs a reference, switch rows rather than trying to send it. Check the errors and credits page for how to read a 400 body.

• n is 1 or 4, never 2 or 3.
• Use resolution, not image_size.
• No references.
• Verify the row id and ratio list in the catalog before shipping.

Handling a 400 on n

If you wrap Soul in a shared helper that accepts any n, add a row-specific rule. For higgsfield/soul, round n up to 4 when it is greater than 1, then keep only the images you need. Rounding up wastes some spend, so tell the caller what it will cost: four images at 1080p is $0.03.

Do not split an n of 3 into one call of 1 and one call of 2, since 2 is rejected. Use one call of 4 or three calls of 1.

Where Soul fits

With a billed price of half a cent to under a cent, Soul is a draft engine: use it to explore a hundred looks, then move the winners to a row that takes references and offers higher fidelity controls. Because it is text-only, the drafts must be described in words, so write prompts you could hand to a photographer.

The seven ratios it lists include the common feed and story shapes, so check the descriptor for your exact placement before a large run.

Checking before you ship

Add a test that calls your helper with n of 1, 2, 3 and 4 against Soul and asserts the outcomes: 1 and 4 succeed, 2 and 3 are rewritten before sending. A test of that kind is cheap, since the failing cases never reach a provider, and it protects a pipeline from a change in the helper that forgets the rule.

Also assert that image_size is never sent on this row. Use aspect_ratio and resolution only.