spora-ai / spora-plugin-openai-image

v0.6.0 2026-10-07 06:12 UTC

Requires

• php: ^8.4.1
• spora-ai/spora-core: >=0.30.0 <2.0.0
• symfony/event-dispatcher: ^8.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.94
• mockery/mockery: ^1.6
• pestphp/pest: ^4.0
• phpstan/phpstan: ^2.1
• phpstan/phpstan-mockery: ^2.0

Suggests

• spora-ai/spora-plugin-media-archive: Browse, filter, and download images generated by this plugin.

MIT

Published on Packagist.org on 2026-10-07 10:00 UTC

README

This plugin provides the image_openai tool using the OpenAI Image API contract. Configure api_key, base_url, and model per agent so compatible providers can be used without code changes.

Generated base64 images are ingested into Spora's Media Archive when available. If the archive is unavailable or ingestion fails, the tool returns a data URL fallback.

The tool exposes two operations:

• generate — single image from a text prompt. Calls POST {base_url}/images/generations. The expected response shape is data[].b64_json.

• generate_variations — one or more images (default 3, min 1, max 8), or semantic variations of an existing image. Approval-gated by default.

  • Prompt-based (default): POST {base_url}/images/generations with n independent samples from the same prompt.
  • Image-based (input_image supplied): POST {base_url}/images/edits (multipart upload). input_image accepts an http(s) URL, a data: URI, a 36-char Media Archive UUID, or an opaque /api/v1/assets/<uuid>.<ext> URL. The plugin resolves Media Archive references server-side so the bytes never enter the chat context. The prompt becomes the change to make to the source image. Providers that still serve only the retired /images/variations endpoint are answered by a fallback to it.

Companion plugins

Listed in composer.json under suggest:

• spora-ai/spora-plugin-media-archive — browse, filter, and download images generated by this plugin. Ingestion is best-effort; if the plugin is absent, the tool returns a data URL fallback.

Translations

This plugin ships a German catalogue at locales/de.json, declared through translationsPaths() in src/OpenAIImagePlugin.php. The host merges it under core's own catalogue, so a German install reads the plugin's operator copy in German.

The key is the English source string, byte for byte — editing the English in the source changes the key, so the old entry stops matching and the new English has no entry. The gate is this repository's own tests/Unit/LocaleCatalogTest.php: it fails on an empty translation, on a translation identical to its key, and on a key the source no longer produces.

Translated

• the tool's display name — OpenAI Image
• the four #[ToolSetting] descriptions
• the plugin.json description

Never translated — these strings are read by the model, so the operator sees exactly what the model sees:

• #[Tool].description
• #[ToolOperation].description
• #[ToolParameter].description
• every #[ToolSetting].label and its option labels, including the labels of settings that carry exposeToLlm: true

See the plugin author guide → Translations.