← Back to blog

Image Prompt API: Build Better Stable Diffusion & ComfyUI Prompts

If you generate images with Stable Diffusion, you already know the pain: a perfectly good idea produces a muddy, off-model result because the prompt was underspecified. One word choice decides between a cinematic portrait and a plastic mess. The fix is not more imagination — it is prompt structure. The Prompt Director API turns a plain-language description into a complete, model-ready prompt package: positive prompt, negative prompt, sampler settings, and drop-in mappings for ComfyUI and Stable Diffusion WebUI.

The base endpoint is free — no API key, no signup — and it is fast enough to call from a script on every generation. An optional one-credit Advanced Optimizer runs a two-stage DeepSeek specialist and critic pass for harder scenes. Here is how to use it from curl, Python, or an MCP-capable agent.

What the API returns

Send one field — request — and Prompt Director returns a structured package instead of a single string:

• positive_prompt — quality tags, subject count, your scene, framing, style, and lighting assembled in a sensible order.
• negative_prompt — model-quality negatives plus your avoid terms.
• recommended_settings — width, height, steps, CFG, sampler, scheduler, and a -1 seed that says "randomize."
• integrations — which ComfyUI nodes to paste into (CLIP Text Encode (Prompt) / CLIP Text Encode (Negative)) and the matching A1111 /sdapi/v1/txt2img field names.
• strategy and warnings — honest notes about how to condition multi-subject scenes.

Because the output is JSON, you can pipe it straight into your ComfyUI workflow generator, an A1111 client, or a pipeline that renders the image for you.

Quick start: one curl call (free)

curl -s https://agentmediatools.com/api/prompt-director \
  -H "Content-Type: application/json" \
  -d '{
    "request": "A samurai standing in a rainy neon alley, katana drawn, steam rising from the pavement",
    "medium": "anime",
    "aspect_ratio": "landscape",
    "framing": "wide-shot",
    "style": "cyberpunk, dramatic rim light",
    "avoid": "text, watermark, extra weapons"
  }'

No key is required for this endpoint. A trimmed response looks like:

{
  "version": "1.0",
  "medium": "anime",
  "aspect_ratio": "landscape",
  "framing": "wide-shot",
  "subject_count": 1,
  "strategy": "single-pass text-to-image",
  "positive_prompt": "masterpiece, best quality, 1girl, ...",
  "negative_prompt": "child, teen, underage, young-looking, ...",
  "recommended_settings": {
    "width": 1344, "height": 768, "steps": 32, "cfg": 6.5,
    "sampler": "dpmpp_2m", "scheduler": "karras", "seed": -1
  },
  "integrations": {
    "comfyui": { "positive_node": "CLIP Text Encode (Prompt)",
                 "negative_node": "CLIP Text Encode (Negative)" },
    "stable_diffusion_webui": { "endpoint": "/sdapi/v1/txt2img",
                 "positive_field": "prompt", "negative_field": "negative_prompt" }
  },
  "warnings": []
}

Exact dimensions and sampler values depend on the medium and aspect ratio you choose — let the response be the source of truth instead of hard-coding numbers.

Python example with requests

For a script or agent loop, the same call in Python:

import requests

r = requests.post("https://agentmediatools.com/api/prompt-director", json={
    "request": "A cozy cabin in a snowy pine forest at dusk, warm windows glowing",
    "medium": "realistic",
    "aspect_ratio": "landscape",
    "framing": "wide-shot",
    "style": "photorealistic, soft golden hour light",
    "avoid": "people, cars",
})
r.raise_for_status()
pkg = r.json()

print(pkg["positive_prompt"])
print(pkg["negative_prompt"])
print(pkg["recommended_settings"])
# Feed straight into your ComfyUI client:
#   comfyui_api.txt2img(prompt=pkg["positive_prompt"],
#                       negative_prompt=pkg["negative_prompt"],
#                       **pkg["recommended_settings"])

Wrap the call in a small function and you have a repeatable "idea → prompt package" step for every image in your pipeline.

Request fields and rules

Everything except request is optional, but the controls matter for consistent output:

Field	Values	Default	Notes
request	text	—	Required, up to 5,000 characters
medium	anime, realistic	anime	Swaps quality presets and negative sets
aspect_ratio	portrait, square, landscape	portrait	Drives returned width/height
framing	close-up, portrait, full-body, wide-shot	full-body	Landscape defaults to wide-shot
subject_count	integer 1–6	1	3+ requires square or landscape
target_model	auto, illustrious, pony, sdxl, flux	auto	Picks the model family hints
interface	comfyui, automatic1111, forge	comfyui	Controls integration mapping
conditioning	auto, prompt-only, regional, controlnet	auto	Set your workflow's approach
style / avoid	text	—	Injected into positive / negative
checkpoint / loras	text	—	Optional exact names + trigger words

Invalid values return a 400 with a clear error, so a caller can fix the payload without guessing. Safety-policy failures also include a machine-readable code. For example, three subjects with a portrait aspect ratio is rejected because that combination rarely renders well.

Multi-subject scenes: the honest strategy

Prompt Director does not pretend prompting alone fixes everything. The response includes a strategy field:

• 1 subject — single-pass text-to-image; add pose or reference conditioning if you need a specific pose.
• 2 subjects — single pass with pose or reference conditioning recommended, plus a warning to give each person distinct features, actions, and a spatial location.
• 3+ subjects — regional conditioning plus OpenPose, then targeted inpainting of faces, hands, and overlapping interactions.

Use the warnings array in your automation: if your workflow is prompt-only and the strategy calls for masks, surface the warning to the human instead of silently generating a bad image.

Advanced Optimizer: DeepSeek specialist + critic (1 credit)

When the free pass is not enough — a complex composition, a tricky style mashup, or a scene with hard conflicts — call the advanced endpoint. It runs a two-stage DeepSeek pipeline that returns model-specific prompts, an exact subject plan, workflow steps, variants, and conflict repairs. It costs 1 credit on success and requires a logged-in session or an agent API key sent as a Bearer token:

curl -s https://agentmediatools.com/api/prompt-director/advanced \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mt_YOUR_AGENT_KEY" \
  -d '{
    "request": "A dragon made of stained glass, perched on a clock tower at midnight",
    "medium": "anime",
    "aspect_ratio": "portrait",
    "target_model": "illustrious",
    "interface": "comfyui"
  }'

Behavior worth knowing for automation:

• If the request body is invalid, you get a 400 before any optimization or credit charge.
• No credits? A 402 tells you the cost and how many credits you have.
• Only one advanced optimization runs per account at a time — concurrent calls get a 429 instead of double-billing.
• If the DeepSeek service is unavailable, you get a 502 and zero credits are charged; the fallback is included.
• Success responses include a billing block, and the response header X-Credits-Charged is set to 1.

Provider failures degrade to the free prompt package without charging a credit, while invalid requests fail before the optimizer runs.

Using it from MCP

Agent Media Tools exposes the same feature as two MCP tools. direct_image_prompt is free and mirrors the base endpoint. optimize_image_prompt runs the DeepSeek pass, costs 1 credit, and requires the MEDIA_TOOL_AGENT_KEY environment variable. That makes it trivial to call from Claude, Hermes, or any MCP-capable agent — the agent gets the same structured package you would get from curl, without writing HTTP code.

Chain it into an image pipeline

The natural next step is wiring the prompt package into generation. Send the returned positive_prompt, negative_prompt, and recommended_settings to a txt2img call, then post-process the result. You can even let an agent do the whole loop: Prompt Director builds the prompt, an image tool renders it, and a resize or compression step prepares it for delivery.

Start with the free endpoint — there is nothing to configure, and you will see the difference in the very first render.