mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-09 01:50:44 +08:00
oliver
4a23b715a2
本次迁移将网关/通道/工具/技能/脚本与协议资源集中到新结构，统一路径常量与脚本转发机制，减少顶层噪音并保证运行与测试行为一致。 Made-with: Cursor
59 lines
1.8 KiB
Markdown
59 lines
1.8 KiB
Markdown
# 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.
|
|
|