feat: tinyinference-image and tinyinference-video (OpenRouter media generation)

.env.example

@@ -17,3 +17,8 @@
 # Example of a credential a live/network-gated test would need. Tests that
 # require one must skip cleanly when it is unset.
 # EXAMPLE_API_KEY=replace-me
+
+# OpenRouter API key for the live media examples
+# (`live_openrouter_image`, `live_openrouter_video`). They skip when unset.
+# Live runs are billed to this key.
+# OPENROUTER_API_KEY=sk-or-replace-me

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- `tinyinference-image`: the `ImageGenerator` trait, `OpenRouterImageGenerator`
+  (`POST /images`), `MockImageGenerator`, media-reference standards
+  (URL, `data:` URL, bytes, local path → OpenRouter content parts), aspect-ratio,
+  resolution and size normalization, per-model capability pre-flight checks, and
+  a billing-aware OpenRouter media transport usable directly or through a
+  proxying backend.
+- `tinyinference-video`: the `VideoGenerator` trait, `OpenRouterVideoGenerator`
+  (`POST /videos`, `GET /videos/{id}`, `GET /videos/{id}/content`),
+  `wait_for_job` (resume by job id), and `MockVideoGenerator`. A `completed`
+  job with no outputs keeps polling instead of failing.
+
 ## 0.3.0
 
 ### Breaking changes

README.md

@@ -50,8 +50,11 @@ can depend on `tinyinference-llm` for language models,
 `tinyinference-embeddings` for vector generation and retrieval,
 `tinyinference-local` for local runtimes and installers,
 `tinyinference-providers` for provider authentication and routing primitives,
-`tinyinference-voice` for speech inference and streaming-audio mechanics, and
-`tinyinference-core` only for shared infrastructure.
+`tinyinference-voice` for speech inference and streaming-audio mechanics,
+`tinyinference-image` for image generation and the shared media-reference
+standards and OpenRouter media transport,
+`tinyinference-video` for asynchronous video generation (submit, poll,
+download, resume), and `tinyinference-core` only for shared infrastructure.
 
 ## Layout
 
@@ -80,8 +83,26 @@ crates/tinyinference-providers/
 └── src/            OAuth/PKCE flows and provider error classification
 crates/tinyinference-voice/
 └── src/            hosted STT, Piper TTS, cleanup, and PCM streaming helpers
+crates/tinyinference-image/
+└── src/            ImageGenerator, media references and output-shape
+                    normalization, OpenRouter media transport, capabilities
+crates/tinyinference-video/
+└── src/            VideoGenerator, submit/poll/download job loop, resume by id
 ```
 
+### Media generation
+
+`tinyinference-image` and `tinyinference-video` speak OpenRouter's media wire
+format (`POST /images`, `POST /videos`, `GET /videos/{id}`,
+`GET /videos/{id}/content`). The same generators run against OpenRouter
+directly (`MediaAuth::ApiKey`) or against a host backend that proxies those
+routes verbatim (`MediaAuth::Bearer` with `MediaTransport::with_base_url`).
+A generator returns delivered media or an error — never an empty success —
+and every error after a billed submit names the job and says not to resubmit.
+Live smoke tests: `cargo run -p tinyinference-image --example
+live_openrouter_image` and `cargo run -p tinyinference-video --example
+live_openrouter_video` (skip without `OPENROUTER_API_KEY`).
+
 ## Development
 
 ```sh

crates/tinyinference-image/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+name = "tinyinference-image"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Provider-neutral image generation, media references, and OpenRouter transport for Rust."
+documentation = "https://docs.rs/tinyinference-image"
+readme = "../../README.md"
+keywords = ["image-generation", "inference", "openrouter", "media"]
+categories = ["api-bindings", "asynchronous", "multimedia::images"]
+
+[dependencies]
+async-trait = { workspace = true }
+base64 = "0.23"
+bytes = { workspace = true }
+reqwest = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+thiserror = { workspace = true }
+tinyinference-core = { version = "0.3.0", path = "../tinyinference-core" }
+tokio = { workspace = true, features = ["fs"] }
+tracing = { workspace = true }
+
+[dev-dependencies]
+axum = { workspace = true }
+tempfile = { workspace = true }
+tokio = { workspace = true, features = ["fs", "net"] }
+
+[lints]
+workspace = true

crates/tinyinference-image/examples/live_openrouter_image.rs

@@ -0,0 +1,95 @@
+//! Live smoke test: generate an image through OpenRouter and save it.
+//!
+//! Network- and credential-gated. Reads `OPENROUTER_API_KEY` from the
+//! environment, falling back to the workspace `.env` file; exits cleanly
+//! (status 0, "skipped") when neither provides one.
+//!
+//! ```sh
+//! cargo run -p tinyinference-image --example live_openrouter_image
+//! # image-to-image: pass a reference image (path or URL)
+//! LIVE_REFERENCE=path/to/ref.png cargo run -p tinyinference-image --example live_openrouter_image
+//! # optional overrides
+//! LIVE_IMAGE_MODEL=google/gemini-3.1-flash-lite-image LIVE_PROMPT="…" cargo run …
+//! ```
+//!
+//! Output lands in `target/live-media/`.
+
+use std::path::PathBuf;
+use std::time::Instant;
+
+use tinyinference_image::{
+    ImageGenerator, ImageRequest, MediaAuth, MediaReference, OpenRouterImageGenerator,
+};
+
+fn api_key() -> Option<String> {
+    if let Ok(key) = std::env::var("OPENROUTER_API_KEY")
+        && !key.trim().is_empty()
+    {
+        return Some(key.trim().to_owned());
+    }
+    let env_file = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../.env");
+    std::fs::read_to_string(env_file)
+        .ok()?
+        .lines()
+        .find_map(|line| {
+            let value = line.trim().strip_prefix("OPENROUTER_API_KEY=")?;
+            let value = value.trim().trim_matches('"').trim_matches('\'');
+            (!value.is_empty()).then(|| value.to_owned())
+        })
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let Some(key) = api_key() else {
+        println!("skipped: OPENROUTER_API_KEY is not set (env or workspace .env)");
+        return Ok(());
+    };
+    let generator = OpenRouterImageGenerator::new(MediaAuth::ApiKey(key));
+    let model =
+        std::env::var("LIVE_IMAGE_MODEL").unwrap_or_else(|_| generator.default_model().to_owned());
+    let prompt = std::env::var("LIVE_PROMPT").unwrap_or_else(|_| {
+        "A four-panel anime comic of two cheerful engineers shaking hands in front of a glowing \
+         server, bright colors, thick ink outlines"
+            .to_owned()
+    });
+
+    let mut request = ImageRequest::new(prompt)
+        .with_model(&model)
+        .with_aspect_ratio("landscape")
+        .with_seed(42);
+    if let Ok(reference) = std::env::var("LIVE_REFERENCE") {
+        println!("image-to-image with reference {reference}");
+        request = request.with_reference(MediaReference::parse(&reference));
+    }
+
+    let started = Instant::now();
+    let response = generator.generate(request).await?;
+    let out_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../target/live-media");
+    for (index, image) in response.images.iter().enumerate() {
+        let path = image
+            .persist(
+                &out_dir,
+                &format!(
+                    "image-{}-{}-{index}",
+                    model.replace('/', "_"),
+                    response.created.unwrap_or_default()
+                ),
+                "png",
+            )
+            .await?;
+        println!(
+            "saved {} ({} bytes, {})",
+            path.display(),
+            image.data.len(),
+            image.media_type
+        );
+    }
+    println!(
+        "model={} images={} cost_usd={:?} elapsed={:.1}s",
+        response.model,
+        response.images.len(),
+        response.cost_usd,
+        started.elapsed().as_secs_f64()
+    );
+    Ok(())
+}