Browse modules

imagegen

v0.1.0 · compiled with katari 0.1.0

Overview

from the package README

imagegen — edit images with the Gemini image model, as a Katari tool

A single module, imagegen, plus its FFI sidecar src/imagegen.ts: hand it an image file and an instruction, get an edited image file back. The API call lives in the sidecar because the response image must become a blob — the sidecar uploads it over the blob side channel and returns the handle, which lifts into a file for the caller.

  • imagegen.edit_image(image, instruction) — the tool: e.g. "make the sky a sunset", "remove the text". Returns a new image file the caller can view or post.
  • imagegen.provider(api_key = ..., model? = "gemini-2.5-flash-image") — provides the image-model API key (and model id) for the extent of a continuation.

Secrets / env

  • GEMINI_API_KEY — a Google Generative Language API key (the image model is served there). Store it in the runtime: katari env set GEMINI_API_KEY --secret. It is a string of private, passed to the sidecar and never surfaced elsewhere. (The same key the ai.gemini provider uses.)

Sidecar dependencies

src/imagegen.ts imports @katari-lang/port (the image API is called with the built-in fetch). It is declared in package.json; run pnpm install (or npm install) in this package so katari apply can bundle the sidecar. (A pure-Katari consumer that never applies this package does not need it.)

Usage

import imagegen
 
agent recolor(image: file) -> file with io {
  use imagegen.provider(api_key = env.get_secret(key = "GEMINI_API_KEY"))
  imagegen.edit_image(image = image, instruction = "make the sky a sunset")
}

Hand imagegen.edit_image to an AI loop's tool list to let the model edit images on its own.

imagegen

5 declarations

get_imagegen_key#

request
request get_imagegen_key() -> string of private

The image-model API key capability (provided once at the root by use imagegen.provider(...)).

Returns

of private
string
Wire view (JSON Schema)

provider#

agent
agent provider[R, effect E](api_key: string of private, model: string ?= "gemini-2.5-flash-image", continuation: agent(value: null) -> R with {...E, get_imagegen_key, get_imagegen_model}) -> R with E

Provide the image-model API key (and model id) for the extent of the continuation.

Generics

Rtype
Eeffect

Parameters

api_key
of private
string
model?= "gemini-2.5-flash-image"
string
continuation
agent
input
object
value
null
output
R
effects
override
base
E

Returns

R

Effects

E

Inferred type

agent(api_key: string of private, continuation: agent(value: null) -> T0 with get_imagegen_key | get_imagegen_model | E1, model?: string) -> T0 with E1

Wire view — the wire shape is fixed at the call site, where the generic parameters are instantiated.

get_imagegen_model#

request
request get_imagegen_model() -> string

The image model id capability (defaulted by the provider; override via its model).

Returns

string
Wire view (JSON Schema)

gemini_image_edit#

external agent
external agent gemini_image_edit(image: file, instruction: string, model: string, api_key: string of private) -> file

Run one image edit in the sidecar: POST the image + instruction to the Gemini image model, upload the returned image as a blob, hand back its file.

Parameters

image
file
instruction
string
model
string
api_key
of private
string

Returns

file
Wire view (JSON Schema)

edit_image#

agent
agent edit_image(image: file, instruction: string) -> file

Tool: edit an image with an instruction (e.g. "make the sky a sunset", "remove the text"). Pass the image's handle object — a bare {"$katari_ref": "<id>"} suffices; the result is a new image file you can view (view_image) or post (send_files).

Parameters

image
file
instruction
string

Returns

file

Inferred type

agent(image: file, instruction: string) -> file with get_imagegen_key | get_imagegen_model | io
Wire view (JSON Schema)