Package com.tnsai.tools.image

Class ImageGenTools

java.lang.Object

com.tnsai.tools.image.ImageGenTools

public class ImageGenTools
extends Object

Function-shape image-generation tools. Wraps the three most common text-to-image providers behind a uniform @Tool method surface so an LLM can pick "draw me X" and the agent's ToolMethodDispatcher routes the call.

Method	Backend	Auth
dalle3Generate(java.lang.String, java.lang.String, java.lang.String, int)	OpenAI Images API (dall-e-3 / dall-e-2)	OPENAI_API_KEY
fluxGenerate(java.lang.String, java.lang.String, java.lang.String, java.lang.String)	Black Forest Labs FLUX (via Replicate sync)	REPLICATE_API_TOKEN
stabilityGenerate(java.lang.String, java.lang.String, java.lang.String)	Stability AI Stable Image v2 (sd3 / core / ultra)	STABILITY_API_KEY

All three return one or more URLs to the generated image. For DALL-E the URL is provider-hosted and expires in roughly an hour — consumers who need persistence should fetch + restage the bytes themselves (a generic MediaStore SPI is a planned follow-up; this class intentionally stays HTTP-pass-through to keep the dependency surface minimal). FLUX and Stability return URLs that live for the duration documented by each provider.

Implementation deliberately uses OkHttp + Jackson only — no vendor SDK is pulled in. The REST APIs are straightforward and the direct path keeps tnsai-tools's transitive dependency graph lean. Same pattern is already established by AiTools (Gemini Vision input) and MediaTools (Whisper STT, OpenAI TTS).

Cost notes (April 2026 list pricing — provider may change)

• DALL-E 3 standard 1024×1024: $0.04 / image; HD or 1792×1024: $0.08
• FLUX schnell on Replicate: ~$0.003 / image; FLUX dev: ~$0.025
• Stability core: $0.03 / image; sd3 medium: $0.035

Since:

0.8.4

Constructor Summary

Constructors

Constructor	Description
ImageGenTools()	Default no-arg ctor — the only one BuiltInTool.IMAGE_GEN_TOOLS ever calls.

Method Summary

Modifier and Type	Method	Description
String	dalle3Generate(String prompt, String size, String quality, int n)
String	fluxGenerate(String prompt, String model, String aspectRatio, String outputFormat)
String	stabilityGenerate(String prompt, String model, String aspectRatio)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ImageGenTools

public ImageGenTools()

Default no-arg ctor — the only one BuiltInTool.IMAGE_GEN_TOOLS ever calls.

Method Details

dalle3Generate

@Tool(name="dalle3_generate",
      description="Generate an image from a text {prompt} using OpenAI DALL-E 3. Returns a JSON object with a `urls` array (one URL per image) plus the model\'s `revised_prompt` if it rewrote the prompt for safety/clarity. URLs are provider-hosted and expire ~1 hour after generation; fetch + restage if persistence matters. Requires OPENAI_API_KEY.")
public String dalle3Generate(@ToolParam(description="What to draw \u2014 a natural-language scene description")
 String prompt,
 @ToolParam(description="Image size \u2014 one of 1024x1024 (square), 1792x1024 (wide), 1024x1792 (tall); default 1024x1024",required=false,defaultValue="1024x1024")
 String size,
 @ToolParam(description="Quality \u2014 `standard` (fast, $0.04) or `hd` (slow, $0.08); default standard",required=false,defaultValue="standard")
 String quality,
 @ToolParam(description="Number of images to generate (1..1 \u2014 DALL-E 3 currently supports 1 only); default 1",required=false,defaultValue="1")
 int n)
                      throws IOException

Throws:

IOException

fluxGenerate

@Tool(name="flux_generate",
      description="Generate an image from a text {prompt} using Black Forest Labs FLUX via Replicate\'s sync API. Returns a JSON object with a `urls` array. Choose {model} for cost / quality trade-off: `schnell` (fast, ~$0.003), `dev` (balanced, ~$0.025), `pro` (best, ~$0.055). Requires REPLICATE_API_TOKEN.")
public String fluxGenerate(@ToolParam(description="What to draw \u2014 natural-language scene description")
 String prompt,
 @ToolParam(description="FLUX model variant \u2014 `schnell` (fastest), `dev` (balanced), `pro` (best); default schnell",required=false,defaultValue="schnell")
 String model,
 @ToolParam(description="Aspect ratio \u2014 `1:1`, `16:9`, `9:16`, `21:9`, `9:21`, `4:3`, `3:4`, `4:5`, `5:4`, `3:2`, `2:3`; default 1:1",required=false,defaultValue="1:1")
 String aspectRatio,
 @ToolParam(description="Output format \u2014 `webp` (smallest), `jpg`, `png`; default webp",required=false,defaultValue="webp")
 String outputFormat)
                    throws IOException

Throws:

IOException

stabilityGenerate

@Tool(name="stability_generate",
      description="Generate an image from a text {prompt} using Stability AI\'s Stable Image v2 endpoints. Returns a JSON object with a `urls` array. Choose {model}: `core` (cheapest, ~$0.03), `sd3` (default Stable Diffusion 3 medium, ~$0.035), `ultra` (best, ~$0.08). Requires STABILITY_API_KEY.")
public String stabilityGenerate(@ToolParam(description="What to draw \u2014 natural-language scene description")
 String prompt,
 @ToolParam(description="Model \u2014 `core`, `sd3` (Stable Diffusion 3 medium), `ultra`; default core",required=false,defaultValue="core")
 String model,
 @ToolParam(description="Aspect ratio \u2014 `1:1`, `16:9`, `21:9`, `2:3`, `3:2`, `4:5`, `5:4`, `9:16`, `9:21`; default 1:1",required=false,defaultValue="1:1")
 String aspectRatio)
                         throws IOException

Throws:

IOException