Flux Image Generation#

Generate and edit images through AceDataCloud's Flux API.

First-time setup#

1. Install the official Skill with clawhub install @acedatacloud/flux. Check that the ClawHub publisher is @acedatacloud.
2. Sign in at AceDataCloud → Applications, open General application, and check Flux access, balance, and current pricing. Copy its API key, or select Manage Keys → Create for a separate key. Copy the key value without Bearer ; a platform-... management token is not a service API key.
3. If you enable Allowed APIs restrictions, include /flux/images and /flux/tasks. Advanced workflows below may call additional routes.
4. On the OpenClaw Gateway host, put ACEDATACLOUD_API_TOKEN=your_api_key_here in ~/.openclaw/.env, then restart the Gateway and start a new session. For a direct terminal test, run export ACEDATACLOUD_API_TOKEN="your_api_key_here" in that shell. Never put the key in a prompt or commit an .env file.
5. Run the Quick Start below. If it returns a task ID, query that same task until it finishes; do not submit a second billable generation just to check progress.

Illustrated key setup, first run, and troubleshooting · Token details

Quick Start#

bash

curl -X POST https://api.acedata.cloud/flux/images \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "generate", "prompt": "a cat wearing a space helmet, photorealistic", "model": "flux-dev", "async": true}'

Async: See async task polling. Poll via POST /flux/tasks with {"id": "..."}.

Models#

ModelQualitySpeedSizesBest Forflux-devGoodFast256–1440pxQuick generation (default)flux-proHighMedium256–1440pxProduction workflux-2-kleinGoodFastest256–1440pxCompact / lowest-latency Flux 2 generationflux-2-flexHighFast256–1440pxFaster high-quality generationflux-2-proHigherMedium256–1440pxBetter prompt followingflux-2-maxHighestSlow256–1440pxMaximum quality generationflux-kontext-proHighMediumAspect ratiosImage editingflux-kontext-maxHighestSlowAspect ratiosComplex editing

Generate Images#

json

POST /flux/images
{
  "prompt": "a minimalist logo of a mountain",
  "action": "generate",
  "model": "flux-2-pro",
  "size": "1024x1024",
  "count": 1
}

Size Options#

For dev/pro/flux-2 (pixel dimensions):

• "1024x1024", "1344x768", "768x1344", "1024x576", "576x1024"

For kontext (aspect ratios):

• "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "21:9", "9:21"

Edit Images#

Use kontext models for text-guided image editing:

json

POST /flux/images
{
  "prompt": "change the background to a beach sunset",
  "action": "edit",
  "image_url": "https://example.com/photo.jpg",
  "model": "flux-kontext-pro"
}

Gotchas#

• Use pixel dimensions (e.g., "1024x1024") with dev/pro/flux-2 models, aspect ratios (e.g., "16:9") with kontext models
• Editing requires kontext models ( flux-kontext-pro or flux-kontext-max) — other models only support generation
• count parameter generates multiple images in one request (increases cost proportionally)
• flux-2-klein is the lightest Flux 2 model — useful when latency matters more than peak quality
• flux-2-max produces highest quality but is slowest — use dev/klein/flex for iteration and max for final output
• All generation is async — always set "callback_url" to get a task id immediately, then poll /flux/tasks using {"id":"<task_id>"} or {"ids":[...],"action":"retrieve_batch"}

MCP: pip install mcp-flux-pro | Hosted: https://flux.mcp.acedata.cloud/mcp | See all MCP servers

FLUX 3 video tools#

POST /flux/videos generates videos with action=generate (default). Use mode=t2v/i2v/v2v/draft_enhance. T2V needs prompt; I2V also needs keyframes; V2V also needs start_video. Normal video requests support hd/fhd/qhd/uhd, integer duration 5–20 seconds (V2V up to 15) or auto, draft and generate_audio flags. Preserve explicit false.

Draft enhancement uses an owned platform draft_task_id and requires its temporary cache to remain available. It does not promise indefinite retention.

Companion MCP tool: flux_generate_video. CLI command: flux video --request-file. MCP/CLI requests submit asynchronously by default and are polled through the existing /flux/tasks endpoint. For raw HTTP requests, set async=true to receive a task ID immediately. Generation charges use actual output seconds; do not substitute requested duration for measured final usage.