Images: out-of-range size returns 500, dead url/file_path fields, misleading revised_prompt

Summary

Several small but user-facing bugs in POST /v1/images/generations against black-forest-labs/FLUX.2-klein-4B. All independently reproducible.

1. Out-of-range size → 500, not 400

size="1x1"          → HTTP 500 "Image generation failed"     (~12s)
size="99999x99999"  → HTTP 500 "Image generation failed"     (~4s)
size="foo"          → HTTP 400 "size must be in format ..."  ✓ (correct)
size="99x99"        → HTTP 200, silently generates 96x96     (rounded, no indication)
size="512x512"      → HTTP 200, 512x512                      ✓
size=null           → HTTP 200, defaults to 1024x1024        ✓

Format validation exists but range/multiple-of-N validation doesn't — out-of-range crashes the upstream with a generic 500 instead of being rejected with a meaningful 400 at the API boundary. Users hitting 1x1 get the same opaque "Image generation failed" they'd get for a transient outage, so they retry uselessly. For 99x99 the request silently succeeds with a different size than asked — a user-confusion footgun.

2. Dead fields in the response

Every data[0] looks like:

{
  "b64_json": "<base64>",
  "url": null,
  "file_path": null,
  "revised_prompt": "<echo of the prompt>"
}

• url: always null (we're b64-only — response_format: "url" is explicitly rejected). Should be omitted entirely, not included as a null. OpenAI returns either url or b64_json, never both.
• file_path: always null. This is an internal-implementation concept (filesystem path) that shouldn't appear in the public API surface at all.
• revised_prompt: echoes the user's prompt verbatim. The OpenAI semantic is "the model rewrote your prompt to this" (DALL-E 3 does this); FLUX doesn't do prompt revision. Including the echoed value makes it look like a revision happened.

3. Non-OpenAI top-level fields (minor)

id, inference_time_s, peak_memory_mb appear at the top level. Extra fields aren't strictly wrong (clients should ignore unknowns), but peak_memory_mb in particular is an internal observability detail leaking into the public response.

Repro

KEY=sk-32c0476395fd40c795725fc101f33304

# 500 instead of 400
curl -s https://cloud-api.near.ai/v1/images/generations \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"black-forest-labs/FLUX.2-klein-4B","prompt":"x","size":"1x1"}'

# Silent rounding
curl -s ... -d '{"model":"black-forest-labs/FLUX.2-klein-4B","prompt":"x","size":"99x99"}'
# inspect SOF of returned JPEG → 96x96

# Dead-field check (look at response shape)
curl -s ... -d '{"model":"black-forest-labs/FLUX.2-klein-4B","prompt":"x"}' | jq '.data[0] | keys'
# ["b64_json","file_path","revised_prompt","url"]

Suggested fixes (cloud-api side)

1. Validate size upfront: enforce the model's supported width/height range and multiple, return 400 with a list of acceptable sizes when out of range.
2. Either populate url correctly (host the image briefly + return a presigned URL) or omit the key when empty. Same for file_path — remove from the public response shape.
3. When the underlying model doesn't revise the prompt, omit revised_prompt rather than echoing the input.
4. Decide if id/inference_time_s/peak_memory_mb belong in the public response — peak_memory_mb at minimum should be dropped.

Related: #428 (n=2 only returns 1 image — same endpoint).
Found during routine cloud-api smoke test.

Start at the implementation of POST /v1/images/generations and reproduce the documented size cases and response shape with the supplied curl examples. Trace how size validation and the data[0] and top-level response fields are assembled. Done means invalid or unsupported sizes receive a meaningful 400, valid sizes are not silently changed, and fields that are always null, echoed, or internal are absent from the public response.