Jimeng API Image Generation

Generate high-quality AI images using Volcengine's Jimeng 4.0 API with text prompts or image inputs.

Configure Environment Variables

# ~/.zshrc or ~/.zshenv
export VOLC_ACCESSKEY="your_access_key_id"
export VOLC_SECRETKEY="your_secret_access_key"

Output Behavior (Important)

After image generation succeeds, you MUST display the image directly to the user!

When generation completes, output in the following format:

![Generated Image](IMAGE_URL)

**Generation Info:**
- Prompt: [User's original prompt]
- Size: [Image dimensions]
- Save Path: [Local file path, if applicable]

Example Output

![Shiba Inu under cherry blossoms](https://example.com/image.png)

**Generation Info:**
- Prompt: Shiba Inu under cherry blossom tree, warm sunlight, healing art style
- Size: 2304 × 1728
- Save Path: /generated_images/[Generated Image] **important**

Notes

Prefer markdown image syntax ![description](URL) to display images directly
Also provide the online link for easy copying and sharing
If saved locally, display the local file path
For multiple images, display each one with numbered labels

Quick Start

Step 1: Run Generation

# Text-to-image
scripts/generate_image.py "A white Siamese cat sitting on a windowsill, sunlight streaming in"

# With specific size
scripts/generate_image.py "Mountain sunset landscape" --size 2K

# Image-to-image editing
scripts/generate_image.py "Change to watercolor style" --images https://example.com/input.jpg

# Save to file
scripts/generate_image.py "Serene lake at sunset" --output /generated_images/lake.png

API Configuration

Parameter	Value	Description
Endpoint	`https://visual.volcengineapi.com`	API base URL
Submit Action	`CVSync2AsyncSubmitTask`	Submit async generation task
Query Action	`CVSync2AsyncGetResult`	Query task result
Version	`2022-08-31`	API version
Service	`cv`	Service name for signing
Region	`cn-north-1`	Region for signing
req_key	`jimeng_t2i_v40`	Jimeng AI 4.0 model identifier

Image Size Options

Preset Resolutions

Preset	Resolution	Pixels
1K	1024×1024	1,048,576
2K	2048×2048	4,194,304 (default)
4K	4096×4096	16,777,216

Exact Dimensions

Use --width and --height together:

scripts/generate_image.py "prompt" --width 2560 --height 1440

Recommended aspect ratios:

1:1 (2048x2048) - Social media posts
4:3 (2304x1728) - Presentations
16:9 (2560x1440) - Widescreen displays
9:16 (1440x2560) - Mobile vertical
3:2 (2496x1664) - Photography

Constraints:

Width × Height must be in [1024×1024, 4096×4096]
Aspect ratio (width/height) in [1/16, 16]
Recommended: Use 2K+ for better quality

Command-Line Options

scripts/generate_image.py PROMPT [OPTIONS]

Arguments:
  PROMPT              Text prompt for image generation (required, max 800 chars)

Options:
  --size SIZE         Image size: 1K, 2K, 4K or WxH (default: 2K)
  --width WIDTH       Exact width (requires --height)
  --height HEIGHT     Exact height (requires --width)
  --images URL [...]  Input image URLs for image-to-image (max 10)
  --watermark         Add "AI Generated" watermark
  --scale FLOAT       Text influence 0-1 (default: 0.5)
  --force-single      Force single image output
  --output PATH       Download image to file
  --json              Output raw JSON response

Environment Variables:
  VOLC_ACCESSKEY           Access Key ID (required)
  VOLC_SECRETKEY           Secret Access Key (required)
  JIMENG_API_URL           API endpoint (default: https://visual.volcengineapi.com)
  JIMENG_API_TIMEOUT       Request timeout seconds (default: 120)
  JIMENG_POLL_INTERVAL     Polling interval seconds (default: 2)
  JIMENG_MAX_POLL_ATTEMPTS Max polling attempts (default: 60)

Authentication

This skill uses Volcengine IAM v4 signature authentication (HMAC-SHA256). The signing process:

Build canonical request with headers: content-type;host;x-content-sha256;x-date
Calculate SHA256 hash of canonical request
Derive signing key: secret_key → date → region → service → "request"
Sign the string-to-sign with derived key
Add Authorization header to request

Reference: HTTP请求示例

Error Codes

Code	Message	Description
10000	Success	Request successful
50411	Pre Img Risk Not Pass	Input image failed content check
50511	Post Img Risk Not Pass	Output image failed content check
50412	Text Risk Not Pass	Input text failed content check
50413	Post Text Risk Not Pass	Input text contains sensitive words
50429	Request Has Reached API Limit	Rate limit exceeded, retry later
50500	Internal Error	Server error
timeout	Request timeout	Increase JIMENG_API_TIMEOUT

Input/Output Limits

Input Images:

Format: JPEG, PNG only
Max files: 10 images
Max size: 15MB per image
Max resolution: 4096×4096
Aspect ratio (W/H): [1/3, 3]

Output:

Max images: 15 - (input image count)
Format: PNG
URL validity: 24 hours

jimeng-api-image-gen