oclaw/docs/GATEWAY_IMAGE_GENERATE.md

Gateway image.generate Contract

This document describes the Python gateway method image.generate.

Method

• Name: image.generate
• Handler: oclaw/interfaces/gateway/server_methods/image.py

Input Params

• prompt (required, non-empty string)
• provider (optional, non-empty string)
• size (optional, non-empty string)
• quality (optional, non-empty string)
• idempotencyKey (optional, non-empty string; used as requestId when provided)

Behavior

1. If context.image_generate exists, it is used as the primary backend hook.
2. Otherwise, the handler falls back to extensions/image-generation-core/api.py::generate_image.
3. Provider resolution uses:
   • context.image_generation_providers first
   • then context.get_runtime_snapshot()["image_generation_providers"] (if available)
4. Provider selection order:
   • explicit provider param
   • context.config.image.defaultProvider
   • first matched entry in context.config.image.providerPriority
   • first available capable provider
5. Capability filter:
   • providers are considered image-capable when any of the following is true:
     • capabilities.image_generation == true
     • capabilities list contains image / image_generation
     • kind is image / image_generation
     • provider exposes callable generate

Error Semantics

• INVALID_REQUEST:
  • missing/blank prompt
  • invalid optional parameter types/empty strings
• NOT_FOUND:
  • explicit provider is not registered
• UNAVAILABLE:
  • runtime/image backend failure

Success Payload (normalized)

Success responses include normalized fields:

• ok: true
• status: "succeeded"
• requestId: string
• provider: string
• model: string | null
• prompt: string

Provider-specific fields are preserved and merged into the payload.