playbooks

home / skills / vaayne / agent-kit / mcp-tokenflux-images

mcp-tokenflux-images skill

/skills/mcp-tokenflux-images

This skill generates AI images using TokenFlux, guiding you through model selection, input schema, and polling until completion.

npx playbooks add skill vaayne/agent-kit --skill mcp-tokenflux-images

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.7 KB
---
name: mcp-tokenflux-images
description: Generate images using AI models via TokenFlux API. Use when creating AI-generated images, artwork, or visual content. Triggers on "generate image", "create picture", "AI art", "image generation", "TokenFlux".
---

# TokenFlux Image Generation

MCP service at `https://tokenflux.ai/v1/images/mcp` (http) with 4 tools.

## Requirements

- `mh` CLI must be installed. If not available, install with:
  ```bash
  curl -fsSL https://raw.githubusercontent.com/vaayne/mcphub/main/scripts/install.sh | sh
  ```
- `TOKENFLUX_API_KEY` environment variable must be set with your TokenFlux API key

## Usage

List tools: `mh list -u https://tokenflux.ai/v1/images/mcp --header "Authorization:Bearer ${TOKENFLUX_API_KEY}"`

Get tool details: `mh inspect -u https://tokenflux.ai/v1/images/mcp --header "Authorization:Bearer ${TOKENFLUX_API_KEY}" <tool-name>`

Invoke tool: `mh invoke -u https://tokenflux.ai/v1/images/mcp --header "Authorization:Bearer ${TOKENFLUX_API_KEY}" <tool-name> '{"param": "value"}'`

## Workflow

1. **List models first**: Use `listModels` to discover available image generation models
2. **Get model schema**: Use `getModel` with the chosen model_id to get the required input_schema
3. **Generate image**: Use `generateImage` with the correct input format from the schema
4. **Poll if needed**: If generation returns `status: 'processing'`, use `getGeneration` to poll until complete

## Notes

- Run `inspect` before invoking unfamiliar tools to get full parameter schema
- Timeout: 30s default, use `--timeout <seconds>` to adjust
- `generateImage` waits up to 30 seconds; if still processing, poll with `getGeneration`
- Always call `getModel` before `generateImage` to understand the correct input format

## Tools

- **listModels**: List all available VLM models with their IDs, names, descriptions, and pricing. Use this first to discover valid model_id values for generate_image. This tool takes no parameters.
- **getModel**: Get detailed information about a specific VLM model including its input_schema. The input_schema is a JSON Schema describing the required input object for generate_image. Always call this before generate_image to understand the correct input format.
- **generateImage**: Generate an image using a VLM model. IMPORTANT: Call get_model first to get the input_schema for your model. This tool waits up to 30 seconds for completion. If the image is ready, returns {id, status: 'succeeded', images: [...]}. If still processing after 30s, returns {id, status: 'processing'} - use get_generation to poll.
- **getGeneration**: Get the status and result of an image generation request. Use the id returned by generate_image to poll until status is 'succeeded' or 'failed'. Returns {id, model, status, images?, error?, cost?}.

Overview

This skill integrates with the TokenFlux image generation MCP service to produce AI-generated images and artwork. It provides tooling to discover models, inspect model input schemas, submit generation requests, and poll for results. Use it when you need programmatic, schema-driven image creation via the TokenFlux API.

How this skill works

The skill exposes four tools: listModels to discover available VLM models; getModel to retrieve a model's input_schema; generateImage to request image generation (waits up to 30s); and getGeneration to poll a generation request until it succeeds or fails. Always call getModel first to shape the payload according to the model's JSON schema, then call generateImage and use getGeneration if the response is still processing.

When to use it

  • Creating AI-generated illustrations, concept art, or marketing visuals programmatically
  • Automating image generation workflows that must target a specific model schema
  • Integrating image creation into pipelines where polling for completion is required
  • Testing and comparing outputs across multiple VLM models discovered via listModels
  • Building services that need cost/status visibility for generation requests

Best practices

  • Call listModels first to discover supported models and pricing before selecting model_id
  • Always call getModel to retrieve the model's input_schema and validate your payload
  • Use generateImage for quick requests but poll with getGeneration when status is 'processing'
  • Respect the default 30s timeout; increase CLI timeout only when needed for long renders
  • Inspect tool schemas with mh inspect before invoking unfamiliar tools to avoid malformed requests

Example use cases

  • Batch-generate product mockups using a specific VLM model and then poll for results
  • Create on-demand AI artwork for a content platform by validating payloads against getModel input_schema
  • Prototype visual concepts by listing available models and comparing outputs and pricing
  • Integrate image generation into a CI/CD asset pipeline that stores generated images and cost metadata

FAQ

What if generateImage returns status 'processing'?

Use getGeneration with the returned id to poll until status becomes 'succeeded' or 'failed'.

Do I need an API key and CLI installed?

Yes. Set TOKENFLUX_API_KEY in your environment and install the mh CLI before using the MCP endpoints.