jimeng-api-image-gen

Jimeng API 图像生成

使用 Volcengine 的 Jimeng 4.0 API，通过文本提示词或图像输入生成高质量 AI 图像。

配置环境变量

获取 Access Key/Secret Key

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

输出行为（重要）

图像生成成功后，必须直接向用户显示图像！

生成完成后，按以下格式输出：

![Generated Image](IMAGE_URL)

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

输出示例

![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**

注意事项

1. 优先使用 Markdown 图像语法 ![description](URL) 直接显示图像
2. 同时提供在线链接，方便复制和分享
3. 如果保存在本地，显示本地文件路径
4. 对于多张图像，使用编号标签逐张显示

快速开始

步骤 1：运行生成

# 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 配置

参数	值	描述
Endpoint	https://visual.volcengineapi.com	API 基础 URL
Submit Action	CVSync2AsyncSubmitTask	提交异步生成任务
Query Action	CVSync2AsyncGetResult	查询任务结果
Version	2022-08-31	API 版本
Service	cv	签名所用的服务名称
Region	cn-north-1	签名所用的区域
req_key	jimeng_t2i_v40	Jimeng AI 4.0 模型标识符

图像尺寸选项

预设分辨率

预设	分辨率	像素数
1K	1024×1024	1,048,576
2K	2048×2048	4,194,304（默认）
4K	4096×4096	16,777,216

精确尺寸

同时使用 --width 和 --height：

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

推荐宽高比：

• 1:1（2048x2048）- 社交媒体帖子
• 4:3（2304x1728）- 演示文稿
• 16:9（2560x1440）- 宽屏显示器
• 9:16（1440x2560）- 手机竖屏
• 3:2（2496x1664）- 摄影

限制：

• 宽度 × 高度必须在 [1024×1024, 4096×4096] 范围内
• 宽高比（宽度/高度）必须在 [1/16, 16] 范围内
• 建议使用 2K 及以上分辨率以获得更好的质量

命令行选项

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)

身份验证

此技能使用 Volcengine IAM v4 签名身份验证（HMAC-SHA256）。签名流程：

1. 使用以下标头构建规范请求：content-type;host;x-content-sha256;x-date
2. 计算规范请求的 SHA256 哈希值
3. 派生签名密钥：secret_key → date → region → service → "request"
4. 使用派生密钥对待签名字符串进行签名
5. 在请求中添加 Authorization 标头

参考：HTTP 请求示例

错误代码

代码	消息	描述
10000	Success	请求成功
50411	Pre Img Risk Not Pass	输入图像未通过内容检查
50511	Post Img Risk Not Pass	输出图像未通过内容检查
50412	Text Risk Not Pass	输入文本未通过内容检查
50413	Post Text Risk Not Pass	输入文本包含敏感词
50429	Request Has Reached API Limit	超出速率限制，请稍后重试
50500	Internal Error	服务端错误
timeout	Request timeout	增大 JIMENG_API_TIMEOUT

输入/输出限制

输入图像：

• 格式：仅限 JPEG、PNG
• 文件数上限：10 张图像
• 大小上限：每张图像 15MB
• 分辨率上限：4096×4096
• 宽高比（W/H）：[1/3, 3]

输出：

• 图像数上限：15 -（输入图像数量）
• 格式：PNG
• URL 有效期：24 小时

参考文档

• Jimeng AI 4.0 API 文档
• HTTP 请求示例
• Volcengine 控制台
• API 密钥管理