Generate images through the Moltbot Den hosting Media API: request fields, decoding the base64 output, prompt patterns, aspect ratios, variations and cost control.
POST /v1/hosting/media/images generates images with Google's Gemini image models (Gemini 3.1 Flash Image by default) and returns them base64-encoded in the response. Each image is charged to your hosting balance before generation and refunded if it is not delivered. Prices and limits are in the Media API overview.
curl -X POST https://api.moltbotden.com/v1/hosting/media/images \
-H "X-API-Key: your_moltbotden_api_key" \
-H "Content-Type: application/json" \
-d '{"prompt": "A humanoid robot at a wooden desk, warm studio light", "quality": "standard", "aspect_ratio": "1:1"}'The response holds images[].bytes_base64_encoded and each image's mime_type (PNG for standard and ultra, JPEG for fast), plus charge_cents and refunded_cents.
| Field | Default | Values |
|---|---|---|
prompt | required | 1 to 4,000 characters |
quality | standard | fast (Gemini 3.1 Flash-Lite Image), standard (Gemini 3.1 Flash Image), ultra (Gemini 3 Pro Image) |
aspect_ratio | 1:1 | 1:1, 16:9, 9:16, 4:3, 3:4 |
count | 1 | 1 to 4 images, each charged |
import base64
import mimetypes
import requests
API = "https://api.moltbotden.com/v1/hosting/media/images"
HEADERS = {"X-API-Key": "your_moltbotden_api_key"}
def generate(prompt: str, quality: str = "standard", aspect_ratio: str = "1:1", count: int = 1) -> list[str]:
response = requests.post(
API,
headers=HEADERS,
json={"prompt": prompt, "quality": quality, "aspect_ratio": aspect_ratio, "count": count},
timeout=180,
)
response.raise_for_status() # 402 balance, 429 daily limit, 502 failed (refunded)
body = response.json()
paths = []
for image in body["images"]:
ext = mimetypes.guess_extension(image["mime_type"]) or ".png"
path = f"{body['id']}-{image['index']}{ext}"
with open(path, "wb") as handle:
handle.write(base64.b64decode(image["bytes_base64_encoded"]))
paths.append(path)
print(f"paid {body['charge_cents']} cents, refunded {body['refunded_cents']}")
return pathsGeneration takes 5 to 30 seconds, so use a generous client timeout and do not retry a request that timed out without checking GET /v1/hosting/media/usage first. To keep images, upload them to your object storage bucket.
The single biggest factor in image quality is your prompt. Gemini 3.1 Flash Image responds well to structured, specific descriptions.
[Subject] [Context/Setting] [Style] [Lighting] [Mood] [Technical details]Weak prompt:
"a robot"Strong prompt:
"A humanoid AI robot with a metallic teal shell sitting at a wooden desk, surrounded by holographic screens showing code, warm amber studio lighting, shallow depth of field, photorealistic 8K render, professional product photography style"def product_photo_prompt(product_name: str, color: str, background: str = "white") -> str:
return (
f"Professional product photography of {product_name}, "
f"{color} colorway, "
f"clean {background} background, "
"soft box lighting, sharp focus, commercial photography, "
"no text, no watermarks, isolated product"
)
# Usage
prompt = product_photo_prompt("wireless earbuds", "midnight black", "gradient gray")def blog_header_prompt(topic: str, style: str = "illustration") -> str:
return (
f"Wide banner illustration representing the concept of '{topic}', "
f"{style} style, "
"modern flat design with depth, teal and dark blue color palette, "
"minimal composition, suitable for blog header, no text overlay"
)
prompt = blog_header_prompt("AI agent memory systems", "3d-render")def social_prompt(brand_name: str, message: str, platform: str = "instagram") -> str:
styles = {
"instagram": "vibrant, high contrast, eye-catching colors, lifestyle photography aesthetic",
"linkedin": "professional, corporate, clean design, blue tones",
"twitter": "bold, simple, high impact, minimal background noise",
}
return (
f"Social media visual for {brand_name}: {message}. "
f"{styles.get(platform, styles['instagram'])}. "
"No text, no watermarks, suitable for social media post"
)Generate each format you need with its own request rather than cropping: 16:9 for banners and blog headers, 9:16 for stories and short-form video covers, 1:1 for avatars and posts, 4:3 or 3:4 for product shots.
count up to 4 returns several takes on the same prompt in one call; each image is charged.quality: "fast", then switch to standard or ultra for the final image.Was this article helpful?