Skip to content

Latest commit

 

History

History
157 lines (132 loc) · 6.61 KB

gguu.md

File metadata and controls

157 lines (132 loc) · 6.61 KB

GGUU AI image generation

MultiLLM exposes GGUU AI as a credential-isolated OpenAI Images provider. The normalized IDs use gguu:<provider-model>; built in are gguu:gpt-image-2, gguu:gpt-image-2.5, gguu:gpt-image-2.5-sunburst and gguu:gpt-image-2.5-flare. GGUU keys belong to one group, so Grok Imagine is a second provider, gguu-grok, with gguu-grok:grok-imagine-image-2.0 and gguu-grok:grok-imagine-image-quality. All are priced at a flat ¥0.04 per image from 1K to 4K on GGUU's public model plaza. GGUU is the first provider of every automatic image route (media generation). Native requests use the /gguu/* namespace. Chat and Responses routes are not advertised because GGUU's GPT Image 2 guide documents the Images API only.

Configuration

Set the provider credential without committing it:

GGUU_API_KEY=your-gguu-api-key
# Optional compatibility alias: GGUUAI_API_KEY=your-gguu-api-key
GGUU_GROK_API_KEY=your-gguu-grok-image-group-key
# Optional compatibility alias: GGUUAI_API_KEY_GROK=your-gguu-grok-image-group-key

GGUU_API_KEY is preferred. Existing installations that use GGUUAI_API_KEY remain supported. GGUU_API_KEY needs a gpt-image group key and GGUU_GROK_API_KEY a Grok-image group key; either provider can be configured alone. The Grok provider's native namespace is /gguu-grok/*.

The global /v1/models list, admin model list, Operations catalog, and setup guide automatically refresh configured image-relay catalogs on first read and then at most once every five minutes per process. This repopulates discovery after a container restart even when its local catalog database is ephemeral. Failed refreshes retain the last good list and wait one minute before retrying. Discovery only makes model-list requests; it does not generate images.

New versioned GPT Image IDs receive the image-generation capability even when the relay omits modality metadata. Explicit output-modality metadata takes precedence. Other models are not assumed to generate images merely because they appear on the same relay. Clients that cache /v1/models must reload their model list to see newly discovered IDs.

The built-in primary origin is https://gguuai.com. The bounded backup origin is https://api.aiaimax.com. A safe GET /v1/models transport failure can use the backup automatically. A paid POST is replayed only after a definite transport failure and only when the client supplied an Idempotency-Key. Upstream HTTP errors are returned without cross-origin retry.

GGUU's public guide does not state whether idempotency keys are deduplicated across both hostnames. Omit Idempotency-Key to disable paid-request replay, or confirm GGUU's current behavior before relying on automatic POST failover.

For Cloudflare, store the credential as a Worker secret. Adding a secret creates and deploys a Worker version:

npx wrangler secret put GGUU_API_KEY
npx wrangler secret put GGUU_GROK_API_KEY

Unified image generation

curl "$PROXY_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $MULTILLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gguu:gpt-image-2",
    "prompt": "An orange cat wearing sunglasses, cyberpunk style",
    "size": "3840x2160",
    "quality": "high",
    "moderation": "low",
    "output_format": "png",
    "response_format": "url",
    "n": 1
  }'

The unified endpoint removes the gguu: prefix and preserves the remaining OpenAI Images request and response fields. auto:image starts with gguu:gpt-image@latest: every GPT Image model GGUU's catalog lists, newest version first, at max quality. On 2026-11-08 that was gguu:gpt-image-2.6, then 2.5 Sunburst, 2.5 Flare and GPT Image 2. A later release leads the route as soon as GGUU lists it, with no code change (newest model placeholders). auto:gpt-image-2.5 stays on the 2.5 family. Every GPT Image version receives the automatic moderation: "low" default. auto:image and auto:image-fast also try gguu-grok:grok-imagine-image@latest (Grok Imagine Image 2.0 today) after the GPT Image models, which receives aspect_ratio, resolution and a low or medium quality instead of size.

Opt-in quality_check on the unified endpoint grades the generated image and can request up to two further takes. Each take stays on the selected GGUU model/provider; QA never switches a generated GGUU image to another provider. The judge defaults to free:vision, subject to key controls, and does not default to Gemini. See quality checks for fields, costs and failure behavior.

Native endpoints

Method MultiLLM path Purpose
GET /gguu/v1/models Live provider catalog
POST /gguu/v1/images/generations Text-to-image generation
POST /gguu/v1/images/edits Multipart image editing

Native text-to-image example:

curl "$PROXY_BASE_URL/gguu/v1/images/generations" \
  -H "Authorization: Bearer $MULTILLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A glass observatory at sunrise",
    "size": "2048x2048",
    "quality": "high",
    "moderation": "low",
    "output_format": "png",
    "response_format": "b64_json",
    "n": 1
  }'

Native multipart edit example:

curl "$PROXY_BASE_URL/gguu/v1/images/edits" \
  -H "Authorization: Bearer $MULTILLM_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Remove the sunglasses and add a hat" \
  -F "[email protected]" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "input_fidelity=high" \
  -F "output_format=png" \
  -F "response_format=url"

The proxy preserves the multipart boundary and binary body without JSON normalization.

GPT Image 2 provider constraints

  • model is gpt-image-2.
  • n must be 1.
  • size may be auto or a valid size up to 3840x2160; dimensions must be multiples of 16, total pixels must be between 655,360 and 8,294,400, and the longest-to-shortest-side ratio must not exceed 3:1.
  • quality accepts low, medium, high, or auto.
  • moderation accepts low or auto; MultiLLM defaults it to low.
  • response_format accepts url or b64_json.
  • output_format should be png or jpeg.
  • Image edits accept one image, an optional PNG mask, and optional input_fidelity=high.
  • Streaming and partial-image events are not supported by this route.

Use the live /gguu/v1/models response and the provider dashboard as the source of truth for newly listed models and their limits; the constraints above describe gpt-image-2, not a verified generation contract for every newer ID.