Image generation

BharatRouter serves text-to-image the same way it serves chat and audio: one API key, the OpenAI wire format, INR pricing. Image models are a routed modality — a request is expanded into an ordered candidate list and tried with circuit-breaker failover across providers. The route that served the request is echoed in the x-br-provider response header.

1. Overview

Served text-to-image over an OpenAI-compatible surface. Today it is BYOK-only: open models FLUX.1 and SDXL route across multiple providers for price/latency/failover using your own provider key. A first-party, India-resident Krutrim Cloud image SKU is planned but not yet enabled — so there is no platform-billed or India-resident image route at the moment.

2. Endpoint

POST /v1/images/generations — JSON body. The reply is the OpenAI images shape: { "created": …, "data": [{ "url" | "b64_json" }] }. Every failure returns a clean OpenAI-shaped error object — never a fake 200with an empty data array.

3. Parameters

BharatRouter extras (same as chat/audio): provider (pin a provider), data_policy ("india_only"), optimize(cost/latency/quality/…), exclude(drop providers/models), and upstream_key (per-request BYOK).

4. India residency

Set "data_policy": "india_only" to pin a request to India-resident routes. There is no India-resident image route enabled today (the first-party Krutrim image SKU is pending), so india_only currently returns an honestno_route for every image model rather than silently leaving the country. This flips on automatically once the Krutrim image route is enabled.

5. Supported models

Every image route is BYOK-only (bring your own provider key): metered for usage value and budget governance, but no BharatRouter money debit(cost_uinr = 0) — the per-image prices in the catalog are estimates, not charges. Providers are reached three ways: a clean passthrough (the OpenAI/images/generations wire shape), a bespoke per-provider adapter, or an async submit-and-poll adapter (bounded — a job that never finishes fails cleanly, it never hangs).

Provider tiers

URL expiry caveat. DashScope, Replicate, MiniMax and Seedream return image URLs that expire ~24h after generation; Gemini (and Imagen) returnbase64 only. In v1 BharatRouter passes the provider URL or base64 throughas-is — there is no re-hosting store — so if you need a durable copy, request"response_format": "b64_json" where the provider supports it, or download the URL promptly.

6. BYOK

The foreign SDXL/FLUX routes are bring-your-own-key: save a provider key (Account → Provider keys) or pass upstream_key per request, and BharatRouter routes to that provider on your key. BYOK requests are metered for usage value and budget governance but incur no BharatRouter money debit — identical to chat. Per-imageinrPerImage is a catalog estimate of usage value, not a charge.

7. Examples

URL response (default):

curl https://api.bharatrouter.com/v1/images/generations \
  -H "Authorization: Bearer br-..." -H "Content-Type: application/json" \
  -d '{
    "model": "sdxl",
    "prompt": "a lotus blooming over a misty lake at dawn",
    "n": 1,
    "size": "1024x1024",
    "data_policy": "india_only"
  }'

Base64 response (b64_json):

curl https://api.bharatrouter.com/v1/images/generations \
  -H "Authorization: Bearer br-..." -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-schnell",
    "prompt": "a peacock in a monsoon garden, watercolour",
    "response_format": "b64_json",
    "upstream_key": "YOUR_PROVIDER_KEY"
  }'

8. Pricing

Flat INR per generated image (v1). Cost is metered through the standard billable path (non-BYOK, successful, standard tier) and surfaces inUsage & activity like every other request. Per-megapixel × steps metering is deferred.

Note: the per-image prices in the catalog areestimates pending confirmation and may change before general availability.

9. Image Sangam (best-of-N)

Image Sangam is the image analog of Sangamconsensus: a panel of image models generates in parallel, and an India-resident vision judge picks the single best image by prompt-adherence, correctness, and quality. Because you select one image (you can't merge pixels), the image "synthesizer" is a best-of-N judge, not a fuse. This is distinct from the console's COMPARE grid (which just shows all N) and from chat Sangam's text synthesizer.

Call it exactly like any image model — the built-in id isbharatrouter/image-sangam (panel: flux-1-schnell +flux-1-dev + sdxl; judge: a vision model). The reply is the normal OpenAI images shape with the chosen image, plus a br_sangam block (and anx-br-sangam header) describing the panel, the chosen index, the judge, and whether judging actually ran.

curl https://api.bharatrouter.com/v1/images/generations \
  -H "Authorization: Bearer br-..." -H "Content-Type: application/json" \
  -d '{
    "model": "bharatrouter/image-sangam",
    "prompt": "a lotus blooming over a misty lake at dawn",
    "response_format": "b64_json",
    "upstream_key": "YOUR_PROVIDER_KEY"
  }'
# → { "created": …, "data": [{ "b64_json": "…chosen…" }],
#     "br_sangam": { "kind": "image",
#       "panel": [{"model":"flux-1-schnell","provider":"…","ok":true}, …],
#       "chosen": {"model":"flux-1-dev","provider":"…","index":0},
#       "judge_model": "qwen2.5-vl-7b-instruct", "judged": true,
#       "reason": "best matched the prompt's lighting and composition" } }

Residency. The panel images may be foreign-BYOK — that is your own BYOK choice, and they left India at generation time. The judge is independent: under "data_policy": "india_only" (or a residency:india variant) the judge sub-call pins india_only in its body, so the generated images never leave the country to be scored. If no India-resident vision route is available underindia_only, the judge simply fails open (below) rather than routing off-shore.

Cost ≈ the panel per-image usage-value + one judge call. Each panel image meters through the standard images path and the judge meters through the standard chat path — no new money code, no double-charge.

Fail-open (never worse than a single generation). If the judge errors, times out, or returns garbage, the first successful panel image is returned withjudged:false. If only one panel image succeeds it is returned without a judge call; if none succeed you get the images plane's normal clean error — never a fake200.

10. Privacy

The image prompt is content. BharatRouter iszero-retention by default (DPDP): the prompt is forwarded to the chosen provider to generate the image and is never logged — only routing and metering metadata (model, provider, image count, status, latency, residency) is recorded. Image Sangam is the same: the br_sangam / x-br-sangam metadata iscontent-free (panel size, chosen index, judge model, judged flag) — never image bytes or the prompt; the images forwarded to the judge are never logged.