jimeng-api

Jimeng API

Overview

This skill enables image generation using a locally deployed Jimeng API service (Docker). It converts text prompts into high-quality images and automatically downloads them to the project's /pic folder. The skill supports text-to-image generation, image-to-image composition, customizable aspect ratios (1:1, 16:9, etc.), and multiple resolution levels (1k, 2k, 4k).

API Endpoint: http://localhost:5100

When to Use This Skill

Use this skill when users request:

• "使用即梦生成图片 [描述]"
• "Generate an image using Jimeng: [description]"
• "Create artwork showing [scene/concept]"
• "Make an illustration of [subject]"
• "Generate a 4K image of [description]"
• "Transform this image to [style]" (image-to-image)
• Any request involving Jimeng AI image generation or visual content creation

Quick Start

Prerequisites

IMPORTANT: The Jimeng API must be running locally via Docker before using this skill.

Region-specific prefixes:

• 国内站: Direct sessionid (e.g., your_session_id)
• 美国站: Add us- prefix (e.g., us-your_session_id)
• 香港站: Add hk- prefix (e.g., hk-your_session_id)
• 日本站: Add jp- prefix (e.g., jp-your_session_id)
• 新加坡站: Add sg- prefix (e.g., sg-your_session_id)

⚠️ nanobanana Model Resolution Rules:

• US site (us-): Fixed at 1024×1024 with 2k resolution; ignores user-provided ratio and resolution parameters
• HK/JP/SG sites (hk-/jp-/sg-): Forced 1k resolution, but supports custom ratio parameters (e.g., 16:9, 4:3)
• Domestic site (CN): Does not support nanobanana model; use jimeng series instead

Always ask the user for their Session ID before proceeding, as the skill does not include a pre-configured credential.

Example prompt to user:

"要使用即梦API生成图片,我需要您的Session ID。您可以从即梦网站(jimeng.jianying.com)的浏览器Cookie中获取 sessionid。

如果使用国际站,请在sessionid前添加对应前缀(us-/hk-/jp-/sg-)。

请提供您的 Session ID。"

Parameter Usage Guidelines

⚠️⚠️ IMPORTANT PARAMETER DISCIPLINE

• ✅ ONLY PASS PARAMETERS THE USER EXPLICITLY MENTIONS.
• ❌ DO NOT GUESS OR ADD UNSPECIFIED PARAMETERS.
• ✅ LET THE SCRIPT USE BUILT-IN DEFAULTS when the user did not specify:
• ratio: 1:1
• resolution: 2k
• model: jimeng-4.0
• intelligent_ratio: false

Rationale: Tools may “helpfully” add options (e.g., --ratio 16:9) that the user didn’t request, overriding script defaults. This is prohibited. Pass only the parameters the user asked for; otherwise, rely on defaults.

Basic Workflow

1. Receive user request for image generation
2. Request Session ID from the user if not already provided
3. Clarify requirements:
4. Text prompt (文生图) or input images (图生图)
5. Model selection (jimeng-4.0, jimeng-3.1, etc.)
6. Aspect ratio (1:1, 16:9, 4:3, etc.)
7. Resolution (1k, 2k, 4k)
8. Intelligent ratio (auto-detect based on prompt keywords)
9. Execute generation using the generate_image.py script — REMINDER: only pass parameters explicitly requested by the user; do not add/guess any optional flags
10. Report results — show file paths only. DO NOT READ/OPEN/ANALYZE GENERATED IMAGES. DO NOT CALL ANY READ TOOL (e.g., Read, view_image). STOP AFTER SAVING.

Image Generation Tasks

Text-to-Image Generation

Generate images from text descriptions.

Minimal default usage (no optional params):

python scripts/generate_image.py text \
    "a cute cat" \
    --session-id "YOUR_SESSION_ID"

Only include optional parameters when the user explicitly requests them.

With user-specified parameters (only when requested):

python scripts/generate_image.py text \
    "futuristic city at sunset with flying cars" \
    --session-id "YOUR_SESSION_ID" \
    --model "jimeng-4.0" \
    --ratio "16:9" \
    --resolution "2k"

Parameters:

• prompt (required): Text description of the desired image
• --session-id: Jimeng session ID (required)
• --model: Model to use (default: jimeng-4.0)
• Options: jimeng-5.0, jimeng-4.6, jimeng-4.5, jimeng-4.1, jimeng-4.0, jimeng-3.1, jimeng-3.0, nanobanana (international only)
• --ratio: Aspect ratio (default: 1:1)
• Options: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9
• --resolution: Resolution level (default: 2k)
• Options: 1k, 2k, 4k
• --intelligent-ratio: Enable smart ratio detection based on prompt keywords ⚠️ Only works for jimeng-4.0/jimeng-4.1/jimeng-4.5 models; other models will ignore this parameter
• --negative-prompt: Negative prompt (elements to avoid)
• --sample-strength: Sampling strength (0.0-1.0)
• --api-url: Custom API URL (default: http://localhost:5100)
• --output-dir: Custom output directory (defaults to project_root/pic)

Image-to-Image Composition

Transform or compose images based on text guidance.

Example user request:

"把这张照片转换成油画风格,色彩鲜艳,笔触明显"

Script usage:

# Using local file
python scripts/generate_image.py image \
    "transform to oil painting style, vivid colors, visible brushstrokes" \
    --session-id "YOUR_SESSION_ID" \
    --images "/path/to/image.jpg"

# Using image URL
python scripts/generate_image.py image \
    "anime style, cute cat" \
    --session-id "YOUR_SESSION_ID" \
    --images "https://example.com/cat.jpg"

# Multiple images (up to 10)
python scripts/generate_image.py image \
    "merge these images into a cohesive scene" \
    --session-id "YOUR_SESSION_ID" \
    --images "image1.jpg" "image2.png" "image3.jpg"

Parameters:

• Same as text-to-image, plus:
• --images: One or more image paths or URLs (1-10 images)

Supported formats: JPG, PNG, WebP Size limit: Recommended <10MB per image

Intelligent Ratio Detection

⚠️ IMPORTANT: This feature only works with the jimeng-4.0, jimeng-4.1, and jimeng-4.5 models. Other models (jimeng-3.0, nanobanana, etc.) will ignore the --intelligent-ratio flag.

Use --intelligent-ratio to automatically select the best aspect ratio based on prompt keywords.

Example:

python scripts/generate_image.py text \
    "奔跑的狮子,竖屏" \
    --session-id "YOUR_SESSION_ID" \
    --model "jimeng-4.0" \
    --intelligent-ratio

Resolution Options

| Resolution | Ratio | Dimensions | |------------|-------|------------| | 1k | 1:1 | 1024×1024 | | | 4:3 | 768×1024 | | | 3:4 | 1024×768 | | | 16:9 | 1024×576 | | | 9:16 | 576×1024 | | | 3:2 | 1024×682 | | | 2:3 | 682×1024 | | | 21:9 | 1195×512 | | 2k (default) | 1:1 | 2048×2048 | | | 16:9 | 2560×1440 | | | 4:3 | 2304×1728 | | 4k | 1:1 | 4096×4096 | | | 16:9 | 5120×2880 | | | 21:9 | 6048×2592 |

Script Details

Location

scripts/generate_image.py

Key Features

• Automatic project root detection (looks for .git, .claude, etc.)
• Creates /pic folder if it doesn't exist
• Timestamps filenames to prevent overwrites (format: jimeng_YYYYMMDD_HHMMSS_N.png)
• Automatic WebP to PNG conversion for maximum compatibility
• Downloads all generated images from API response
• Supports both text-to-image and image-to-image modes
• Handles multipart/form-data for local file uploads
• Error handling for API calls and downloads
• Prints generation statistics

Output Format

• Images are saved to: {project_root}/pic/jimeng_{timestamp}_{index}.png
• All images are automatically converted to PNG format (including WebP sources)
• Each API call generates several variations

Requirements

The script requires:

pip install requests Pillow

Note: Pillow is required for WebP to PNG conversion. If not installed, WebP images will be saved as-is.

Workflow Decision Tree

User requests image generation
    ↓
Is Jimeng API running at localhost:5100?
    ├─ No → Instruct user