agentai_image/lib.rs
1//! # AgentAI Image
2//!
3//! Image generation and editing for [AgentAI](https://crates.io/crates/agentai): from your
4//! code with [`ImageGenerator`], or by an agent with the toolboxes (feature `toolbox`).
5//!
6//! ## Generating images
7//!
8//! ```rust,no_run
9//! use agentai_image::ImageGenerator;
10//!
11//! # async fn run() -> Result<(), agentai_image::ImageError> {
12//! // The provider comes from the model name, the API key from `OPENAI_API_KEY`
13//! let generator = ImageGenerator::new("openai::gpt-image-1")?.with_size("1024x1024");
14//! let response = generator.generate("A lighthouse at dawn").await?;
15//! // response.image is an agentai `Media`, base64 data or a URL
16//! # Ok(())
17//! # }
18//! ```
19//!
20//! With [`with_storage`](ImageGenerator::with_storage) every image is saved in a
21//! [`MediaSave`](storage::MediaSave) and gets an ID. The [`storage`] module (from
22//! `agentai-core`) has the storage traits and [`MemoryStorage`](storage::MemoryStorage).
23//!
24//! ## Tools for agents
25//!
26//! - [`GenerateImageToolBox`]: `generate_image` and `edit_image` (the latter needs a storage). The model
27//! gets the image, or only its metadata as JSON ([`ImageToolOutput`]).
28//! - [`ReadMediaToolBox`]: `read_media` gives the model a stored file by ID.
29//!
30//! ```rust,no_run
31//! # #[cfg(feature = "toolbox")]
32//! # async fn run() -> anyhow::Result<()> {
33//! use agentai::Agent;
34//! use agentai::tool::ToolBoxSet;
35//! use agentai_image::storage::MemoryStorage;
36//! use agentai_image::{GenerateImageToolBox, ImageGenerator, ReadMediaToolBox};
37//!
38//! let storage = MemoryStorage::new();
39//! let mut tools = ToolBoxSet::new();
40//! tools.add_tool(
41//! GenerateImageToolBox::new(ImageGenerator::new("openai::gpt-image-1")?)
42//! .with_storage(storage.clone()),
43//! );
44//! tools.add_tool(ReadMediaToolBox::new(storage.clone()));
45//! let agent = Agent::new("claude-haiku-5-5", "You are an illustrator.")?.with_toolbox(tools);
46//! let result = agent.run::<String>("Draw a lighthouse at dawn").await?;
47//! # Ok(())
48//! # }
49//! ```
50//!
51//! ## Providers
52//!
53//! The image APIs live in [`provider`]: [`openai`](provider::openai) (OpenAI and compatible
54//! servers) and [`openrouter`](provider::openrouter). [`ImageGenerator::new`] picks one from the
55//! model name (`openai::gpt-image-1`, `openrouter::bytedance-seed/seedream-4.5`) with its
56//! settings from environment variables. [`provider::list_models`] lists the image models of a
57//! provider, with names ready for `ImageGenerator::new`:
58//!
59//! ```rust,no_run
60//! # async fn run() -> Result<(), agentai_image::ImageError> {
61//! for model in agentai_image::provider::list_models("openrouter").await? {
62//! println!("{}", model.model);
63//! }
64//! # Ok(())
65//! # }
66//! ```
67//! To set the API key
68//! or base URL in code, build the provider and pass it to [`ImageGenerator::from_provider`]:
69//!
70//! ```rust,no_run
71//! use agentai_image::ImageGenerator;
72//! use agentai_image::provider::openai::OpenAiImageProvider;
73//!
74//! let provider = OpenAiImageProvider::new("gpt-image-1", "sk-...", "https://api.openai.com/v1");
75//! let generator = ImageGenerator::from_provider(provider);
76//! ```
77//!
78//! Implement [`provider::ImageProvider`] to use another API.
79//!
80//! ## Features
81#![doc = document_features::document_features!()]
82
83mod generator;
84pub mod provider;
85#[cfg(feature = "toolbox")]
86mod toolbox;
87
88#[doc(inline)]
89pub use agentai_core::storage;
90pub use generator::ImageGenerator;
91pub use provider::{ImageError, ImageModel, ImageResponse};
92#[cfg(feature = "toolbox")]
93pub use toolbox::{GenerateImageToolBox, ImageToolOutput, ReadMediaToolBox};