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. Image edits (/v1/images/edits)

POST /v1/images/edits — multipart/form-data, the OpenAI image-edit wire shape. Send a source image (one or more files), an optionalmask (transparent pixels mark the region to change), and aprompt. The reply is the same OpenAI images shape as generations. Edit is supported on edit-capable models only — today gpt-image-1and gpt-image-1-mini (BYOK). A non-edit model returns a clearunsupported_operation error.

curl https://api.bharatrouter.com/v1/images/edits \
  -H "Authorization: Bearer br-..." \
  -F model=gpt-image-1 \
  -F image=@source.png \
  -F mask=@mask.png \
  -F prompt="add a red hat" \
  -F upstream_key=YOUR_OPENAI_KEY

Fields: image (required), prompt (required),model, mask, n, size,response_format — plus BR extras provider,data_policy, exclude, upstream_key. BYOK: add your OpenAI key in Suppliers & Catalog, or passupstream_key per request. Metered per delivered image, exactly like generations.

9. 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.

10. 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.