Nby Jimeng API

Jimeng API - 即梦 AI 图片/视频生成

通过本地 Docker 部署的 jimeng-free-api-all 服务（OpenAI 兼容接口），调用即梦 AI 生成图片和视频。

Workflow Overview

Every Jimeng generation task follows these steps:

1. Confirm service — check Docker container jimeng-free-api-all is running on localhost:8000
2. Obtain session ID — check $JIMENG_SESSION_ID env var; if not set, ask the user for their Jimeng sessionid
3. Select endpoint & model — pick the right API endpoint and model for the task (see quick reference below)
4. Call API — execute the curl command with exact headers, endpoint path, and JSON payload (low freedom: follow precisely)
5. Download & save — generated URLs are temporary; immediately download to the user's desired location

Configuration

Credentials (.env)

Check .env existence (priority order):

# Project-level
test -f .nby-skills/nby-jimeng-api/.env && echo "project"
# User-level
test -f "$HOME/.nby-skills/nby-jimeng-api/.env" && echo "user"

If neither exists, ask the user for their Jimeng session ID and offer to save it.

Load credentials:

# Source .env (project-level first, then user-level)
if [ -f .nby-skills/nby-jimeng-api/.env ]; then
  source .nby-skills/nby-jimeng-api/.env
elif [ -f "$HOME/.nby-skills/nby-jimeng-api/.env" ]; then
  source "$HOME/.nby-skills/nby-jimeng-api/.env"
fi

Auth header format: Authorization: Bearer $JIMENG_SESSION_ID

Multiple accounts supported (comma-separated): JIMENG_SESSION_ID=sid1,sid2,sid3

Quick Reference

For full model list and resolution tables, see references/models.md. For detailed API parameters and response formats, see references/api-detail.md. For Seedance multimodal details, see references/seedance.md.

Docker Container Management

# Check status
docker ps --filter name=jimeng-free-api-all

# Start (if not running)
docker run -it -d --init --name jimeng-free-api-all \
  -p 8000:8000 -e TZ=Asia/Shanghai \
  wwwzhouhui569/jimeng-free-api-all:latest

# Stop / Restart / Logs
docker stop jimeng-free-api-all
docker start jimeng-free-api-all
docker logs jimeng-free-api-all --tail 50

Text-to-Image

curl -s -X POST http://localhost:8000/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JIMENG_SESSION_ID" \
  -d '{
    "model": "jimeng-4.6",
    "prompt": "图片描述",
    "ratio": "1:1",
    "resolution": "2k"
  }'

Key params: model, prompt (required), ratio (1:1/4:3/16:9/9:16/...), resolution (1k/2k/4k), negative_prompt, sample_strength (0-1).

Returns data[] with multiple image URLs (typically 4). Download immediately:

curl -s -o output.png "IMAGE_URL"

Image-to-Image

重要: /v1/images/generations 端点的 images 参数实际上不生效（源码未处理），该端点只支持纯文生图。 真正的图生图必须使用 /v1/images/compositions 端点。

方式一：JSON 模式（推荐）

通过 images 传入参考图 URL 数组：

curl -s -X POST http://localhost:8000/v1/images/compositions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JIMENG_SESSION_ID" \
  -d '{
    "model": "jimeng-4.6",
    "prompt": "将图片转换为水彩画风格",
    "images": ["https://example.com/input.jpg"],
    "ratio": "1:1",
    "resolution": "2k"
  }'

方式二：multipart/form-data 文件上传

curl -s -X POST http://localhost:8000/v1/images/compositions \
  -H "Authorization: Bearer $JIMENG_SESSION_ID" \
  -F "model=jimeng-4.6" \
  -F "prompt=将图片转换为水彩画风格" \
  -F "ratio=1:1" \
  -F "resolution=2k" \
  -F "images=@/path/to/input.jpg"

注意: sample_strength 参数在 multipart 模式下可能报错 "Params body.sample_strength invalid"，建议使用 JSON 模式传递该参数。

验证参考图是否生效

成功的图生图返回会包含 input_images 和 composition_type 字段，可用来确认参考图已生效：

{
  "created": 1774966621,
  "input_images": ["https://..."],
  "composition_type": "...",
  "data": [{"url": "https://..."}]
}

Video Generation (Sync)

Blocks until video is ready. May take several minutes.

curl -s -X POST http://localhost:8000/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JIMENG_SESSION_ID" \
  -d '{
    "model": "jimeng-video-3.5-pro",
    "prompt": "视频描述",
    "ratio": "16:9",
    "resolution": "720p",
    "duration": 5
  }'

Key params: duration (5 or 10 sec for normal models, 4-15 for Seedance), file_paths (first/last frame URLs).

Video Generation (Async) — Recommended for long tasks

Submit task:

curl -s -X POST http://localhost:8000/v1/videos/generations/async \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JIMENG_SESSION_ID" \
  -d '{
    "model": "jimeng-video-3.5-pro",
    "prompt": "视频描述",
    "ratio": "16:9",
    "resolution": "720p",
    "duration": 5
  }'

Returns {"task_id": "...", "status": "processing"}.

Query result (blocks until done):

curl -s "http://localhost:8000/v1/videos/generations/async/TASK_ID" \
  -H "Authorization: Bearer $JIMENG_SESSION_ID"

Limits: max 10 concurrent async tasks. Tasks auto-expire after 24 hours.

Seedance 2.0 Multimodal Video

Supports mixed image/video/audio upload. Use @1, @2 placeholders in prompt to reference uploaded files.

curl -X POST http://localhost:8000/v1/videos/generations \
  -H "Authorization: Bearer $JIMENG_SESSION_ID" \
  -F "model=jimeng-video-seedance-2.0" \
  -F "prompt=@1 和 @2 两人开始跳舞" \
  -F "ratio=4:3" \
  -F "duration=4" \
  -F "files=@/path/to/image1.jpg" \
  -F "files=@/path/to/image2.jpg"

For full Seedance details (supported formats, fast mode, audio mixing), see references/seedance.md.

Error Handling

Troubleshooting

# Check container status and logs
docker ps --filter name=jimeng-free-api-all
docker logs jimeng-free-api-all --tail 30

# Test service connectivity
curl -s http://localhost:8000/v1/models | python3 -m json.tool | head -10

# Check if port is in use by another process
lsof -i :8000