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

Jimeng API Detailed Parameters & Responses

Text-to-Image

POST /v1/images/generations

纯文生图端点。注意：该端点的 `images` 参数不生效（源码未处理），不支持图生图。 如需图生图请使用 /v1/images/compositions。

Parameters

Success Response

{
  "created": 1774966621,
  "data": [
    {"url": "https://p26-dreamina-sign.byteimg.com/.../image.png"},
    {"url": "https://p3-dreamina-sign.byteimg.com/.../image.png"},
    {"url": "https://p26-dreamina-sign.byteimg.com/.../image.png"},
    {"url": "https://p26-dreamina-sign.byteimg.com/.../image.png"}
  ]
}

Typically returns 4 images per request.

---

Image-to-Image (Composition)

POST /v1/images/compositions

图生图专用端点。支持两种请求格式：JSON 模式和 multipart/form-data 文件上传模式。

Parameters

Request Format 1: JSON（推荐）

Content-Type: application/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"],
    "sample_strength": 0.5
  }'

Request Format 2: multipart/form-data（文件上传）

通过 images 字段上传本地文件。

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

Success Response

成功的图生图返回会额外包含 input_images 和 composition_type 字段，可用来验证参考图是否生效：

{
  "created": 1774966621,
  "input_images": ["https://..."],
  "composition_type": "...",
  "data": [
    {"url": "https://p26-dreamina-sign.byteimg.com/.../image.png"},
    {"url": "https://p3-dreamina-sign.byteimg.com/.../image.png"},
    {"url": "https://p26-dreamina-sign.byteimg.com/.../image.png"},
    {"url": "https://p26-dreamina-sign.byteimg.com/.../image.png"}
  ]
}

两个端点的区别总结

---

Video Generation (Sync)

POST /v1/videos/generations

Blocks until video is ready. Timeout can be 1-20 minutes depending on queue.

Parameters

Success Response

{
  "created": 1774778988,
  "data": [{
    "url": "https://v3-dreamnia.jimeng.com/.../video.mp4",
    "revised_prompt": "..."
  }]
}

---

Video Generation (Async) — Recommended

Submit Task

POST /v1/videos/generations/async

Same parameters as sync endpoint. Returns immediately.

Submit Response

{
  "created": 1774778941,
  "task_id": "4f2acc30-2b57-11f1-9361-e959a88411c4",
  "status": "processing",
  "message": "任务已提交，请使用 GET /v1/videos/generations/async/{task_id} 查询结果"
}

Query Result

GET /v1/videos/generations/async/:taskId

Blocks until video is ready and returns result.

Query Success Response

{
  "created": 1774778988,
  "task_id": "4f2acc30-2b57-11f1-9361-e959a88411c4",
  "status": "succeeded",
  "data": [{
    "url": "https://v3-dreamnia.jimeng.com/.../video.mp4",
    "revised_prompt": "..."
  }]
}

Query Failure Response

{
  "created": 1774778988,
  "task_id": "4f2acc30-2b57-11f1-9361-e959a88411c4",
  "status": "failed",
  "error": "[API_IMAGE_GENERATION_FAILED] 视频生成超时"
}

Async Constraints

• Max 10 concurrent async tasks; excess submissions return error
• Task data persisted in tmp/async-tasks/ (survives restart)
• Processing tasks auto-resume on service restart
• Completed tasks auto-expire after 24 hours

---

Models List

GET /v1/models

Returns all available models. No auth required.

{
  "data": [
    {"id": "jimeng-5.0", "object": "model", "owned_by": "jimeng-free-api"},
    {"id": "jimeng-4.6", "object": "model", "owned_by": "jimeng-free-api"},
    ...
  ]
}

---

Common Error Responses

Token Expired

{"error": {"message": "Token已失效", "code": -2002}}

Action: Ask user to re-login at jimeng.jianying.com and get new sessionid.

Content Filtered

{"error": {"message": "[API_CONTENT_FILTERED] 内容被过滤"}}

Action: Revise prompt to avoid sensitive/NSFW content.

Credit Insufficient

{"error": {"message": "credit prededuct failed"}}

Action: Switch to another account or wait for daily credit refresh (66 free credits/day).

Generation Failed

{"error": {"message": "[API_IMAGE_GENERATION_FAILED] 图像生成失败"}}

Action: Retry with simpler prompt. For video, try async endpoint.

Shark Anti-Crawl (Seedance only)

Error contains "shark not pass". Action: Ensure container is v0.8.4+ with Chromium installed. First Seedance request auto-launches browser (~seconds).

Jimeng AI Models & Resolution Reference

Image Models

Recommendation: Use jimeng-4.6 for stable quality, jimeng-5.0 for best quality.

Video Models

Video duration:

• Normal models (video-2.0/3.0/3.5): 5 or 10 seconds
• Seedance models: 4-15 seconds (continuous range)

First/last frame support:

• video-3.0, video-3.0-fast, video-3.0-pro: supported (via file_paths)
• video-2.0, video-s2.0: first frame only, no last frame

Image Resolution

Video Resolution

Seedance 2.0 Multimodal Video Generation

Seedance 2.0 is Jimeng's advanced multimodal video model. It supports mixed image/video/audio uploads for intelligent video generation.

Models

Parameters

POST /v1/videos/generations (multipart/form-data)

*Either files or file_paths must be provided.

Supported Media Types

Prompt Placeholders

Reference uploaded files by order:

• @1 / @图1 / @image1 — first uploaded file
• @2 / @图2 / @image2 — second uploaded file
• And so on...

Usage Examples

Multi-image video

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"

Fast mode

curl -X POST http://localhost:8000/v1/videos/generations \
  -H "Authorization: Bearer $JIMENG_SESSION_ID" \
  -F "model=jimeng-video-seedance-2.0-fast" \
  -F "prompt=@1 图片中的人物开始微笑" \
  -F "ratio=4:3" \
  -F "duration=5" \
  -F "files=@/path/to/image1.jpg"

Image + Audio mixing

curl -X POST http://localhost:8000/v1/videos/generations \
  -H "Authorization: Bearer $JIMENG_SESSION_ID" \
  -F "model=jimeng-video-seedance-2.0-fast" \
  -F "prompt=@1 图片中的人物随着音乐 @2 开始跳舞" \
  -F "ratio=9:16" \
  -F "duration=5" \
  -F "files=@/path/to/image.png" \
  -F "files=@/path/to/audio.wav"

JSON mode (with URLs instead of file upload)

curl -s -X POST http://localhost:8000/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JIMENG_SESSION_ID" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "@1 图片中的人物开始微笑",
    "ratio": "4:3",
    "duration": 4,
    "file_paths": ["https://example.com/image.jpg"]
  }'

Async Seedance (recommended for production)

# Submit
curl -s -X POST http://localhost:8000/v1/videos/generations/async \
  -H "Authorization: Bearer $JIMENG_SESSION_ID" \
  -F "model=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"

# Query (returns task_id in submit response)
curl -s "http://localhost:8000/v1/videos/generations/async/TASK_ID" \
  -H "Authorization: Bearer $JIMENG_SESSION_ID"

Troubleshooting

"shark not pass" error

Seedance requests go through a Playwright browser proxy to bypass ByteDance's a_bogus signature check. If you see this error:

1. Ensure container is v0.8.4 or later (image includes Chromium) 2. First Seedance request auto-launches headless browser (~seconds warmup) 3. Each sessionId gets its own browser session; idle sessions auto-cleanup after 10 minutes 4. Only Seedance generate requests use the browser proxy; all other endpoints (image gen, normal video, polling) use direct Node.js requests

Image size limit

Uploaded images must be < 10MB. Larger files may cause upload failure.

Session Security

If sessionid is compromised, use the project's logout tool to forcibly invalidate it:

# Clone the project (if not already)
git clone https://github.com/wwwzhouhui/jimeng-free-api-all.git

# Install deps
pip install playwright && playwright install chromium

# Force logout leaked sessionid
python3 scripts/logout-sessions.py <leaked_sessionid>

Note: ByteDance accounts allow multiple concurrent sessions. Re-logging in does NOT invalidate old sessionids. You must explicitly logout.