Jimeng2API

中文文档

🎨 Free AI Image and Video Generation API Service - Based on reverse engineering of Jimeng AI (China site) and Dreamina (international site).

⭐ If this project helps you, please give it a Star! Your support motivates us to keep improving.

🔔 Watch this project to get notified about new features and updates.

✨ Features

• 🎨 AI Image Generation: Supports multiple models and resolutions (default 2K, supports 4K, 1K).
• 🖼️ Image-to-Image Synthesis: Supports local images or image URLs.
• 🎬 AI Video Generation: Supports text-to-video generation, and adds local image upload for image-to-video on the China site.
• 🌐 International Site Support: Added support for text-to-image and image-to-image APIs on Dreamina international sites. Open an issue if you run into problems.
• 🔄 Smart Polling: Adaptive polling mechanism to optimize generation efficiency.
• 🛡️ Unified Exception Handling: Comprehensive error handling and retry mechanism.
• 📊 Detailed Logs: Structured logging for easy debugging.
• 🐳 Docker Support: Containerized deployment, ready to use out of the box.
• ⚙️ Log Level Control: Dynamically adjust log output level through configuration files.

⭐ Star History

⚠ Risk Warning

• This project is for research and educational purposes only. It does not accept any financial donations or transactions!
• For personal use and research only. Avoid putting pressure on the official servers. Abuse may result in account bans or legal action.
• For personal use and research only. Avoid putting pressure on the official servers. Abuse may result in account bans or legal action.
• For personal use and research only. Avoid putting pressure on the official servers. Abuse may result in account bans or legal action.

✨ New Feature Highlights

📐 ratio and resolution Parameter Support

Image dimensions are now controlled by the ratio and resolution parameters, giving you more flexibility. The default resolution is set to 2k.

curl -X POST http://localhost:5100/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  -d \
    "{\"model\": \"jimeng-4.5\", \"prompt\": \"A beautiful girl, film-like feel\", \"ratio\": \"4:3\", \"resolution\": \"2k\"}"

Supported resolutions: 1k, 2k, 4k

Supported ratios: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9

🚀 Quick Start

Getting sessionid

• Getting your sessionid works the same way on both the China site (Jimeng) and international sites (Dreamina) — If you don’t know how, ask AI.

Note 1: The API endpoints are the same for the China site and international sites, but use different prefixes:

• China site: Use the sessionid directly, e.g., Bearer your_session_id
• US site: Add us- prefix, e.g., Bearer us-your_session_id
• Hong Kong site: Add hk- prefix, e.g., Bearer hk-your_session_id
• Japan site: Add jp- prefix, e.g., Bearer jp-your_session_id
• Singapore site: Add sg- prefix, e.g., Bearer sg-your_session_id

Note 2: Supports binding proxies (HTTP/SOCKS5, etc.) in the Token, see Token Bound Proxy Feature for details.

Note 3: The China site and international sites now support both text-to-image and image-to-image. The nanobanana and nanobananapro models are available on international sites.

Note 4: Resolution rules when using the nanobanana model on international sites:

• US site (us-): Images are fixed at 1024x1024 with 2k resolution, ignoring user-provided ratio and resolution parameters
• Hong Kong/Japan/Singapore sites (hk-/jp-/sg-): Fixed 1k resolution, but supports custom ratio values (e.g., 16:9, 4:3, etc.)

Managed Tokens and API Keys

The service can now manage multiple Jimeng/Dreamina sessionid values server-side. External callers no longer need to send a raw sessionid; they call the OpenAI-compatible endpoints with an API Key issued by this service:

Authorization: Bearer your_client_api_key

Managed tokens are stored in Postgres and selected with round-robin order by sort_order: task 1 uses token1, task 2 uses token2, then the rotation wraps. A background health checker periodically validates tokens, marks expired tokens as unhealthy, and creates alerts.

Admin UI:

http://localhost:5100/admin

The admin UI uses ADMIN_API_KEY. Docker Compose automatically reads .env from the project root. Start by copying the example:

cp .env.example .env

Then edit the secrets in .env:

ADMIN_API_KEY=<generate-a-strong-admin-secret>
TOKEN_ENCRYPTION_KEY=<generate-a-strong-token-encryption-key>
POSTGRES_PASSWORD=<generate-a-strong-database-password>
TOKEN_HEALTH_CHECK_INTERVAL_MS=300000
TOKEN_HEALTH_FAILURE_THRESHOLD=2
DINGTALK_WEBHOOK_URL=<optional DingTalk custom robot webhook>
DINGTALK_AT_MOBILES=<optional comma-separated mobile numbers>
DINGTALK_AT_USER_IDS=<optional comma-separated DingTalk user IDs>
DINGTALK_AT_ALL=false

These secrets must be configured explicitly, and .env should not be committed. External caller API Keys and managed tokens can be created in the admin UI.

When DINGTALK_WEBHOOK_URL is configured, the managed-token health checker sends a DingTalk Markdown notification when it first creates an open alert. Continued failures for the same open alert do not send repeated notifications. Use DINGTALK_AT_MOBILES, DINGTALK_AT_USER_IDS, and DINGTALK_AT_ALL to control mentions.

Environment Requirements

• Node.js 18+
• npm or yarn
• Docker (optional)

Installation and Deployment

Method 1: Docker Compose Local Build (Recommended)

Start command

docker-compose up -d --build

Rebuild/update command

docker-compose up -d --build

Method 2: Direct Run

# Clone the project
git clone https://github.com/f3liiix/jimeng2api.git
cd jimeng2api

# Install dependencies
npm install

# Build files
npm run build

# Start the service
npm run dev

Method 3: Docker Deployment (recommended)

🚀 Quick Start

# Using docker-compose
docker-compose up -d --build

# Or build and run manually
docker build -t jimeng2api .

docker run -d \
  --name jimeng2api \
  -p 5100:5100 \
  --restart unless-stopped \
  jimeng2api

🔧 Common Commands

# Rebuild and start
docker-compose up -d --build

# View service logs
docker logs jimeng2api

# Stop service
docker-compose down

# Enter container for debugging
docker exec -it jimeng2api sh

📊 Docker Image Features

• ✅ Multi-stage build: Optimized image size (170MB)
• ✅ Non-root user: Enhanced security (user:jimeng,)
• ✅ Health check: Automatic service status monitoring
• ✅ Unified port: Uses port 5100 both inside and outside the container
• ✅ Log management: Structured log output

Configuration

configs/dev/service.yml

name: jimeng2api
route: src/api/routes/index.ts
port: 5100

configs/dev/system.yml

requestLog: true
debug: false
log_level: info # Log levels: error, warning, info (default), debug

🤖 Claude Code Skill

This project includes a dedicated Claude Code Skill for quick image generation using the Jimeng API directly within Claude Code conversations.

Features

• 🎯 Quick Generation: Use Jimeng API to generate images directly in conversations
• 📁 Auto-Save: Generated images are automatically saved to the project's /pic directory
• 🔄 Format Conversion: Automatic WebP to PNG conversion
• 🎨 Dual Modes: Supports both text-to-image and image-to-image generation
• ⚙️ Configurable: Customizable ratio, resolution, model parameters, and more

Installation

1. Ensure the jimeng2api service is running:

# Start the service with Docker Compose
docker-compose up -d --build

2. Copy the skill to Claude Code's skills directory:

# Copy to user-level global skills directory
cp -r jimeng2api ~/.claude/skills/

# Or copy to project-level skills directory
cp -r jimeng2api ./.claude/skills/

3. Install Python dependencies:

pip install requests Pillow

Usage Example

In Claude Code, simply use natural language:

User: "my sessionid is xxxxx，Generate a 2K 16:9 image of a futuristic city at sunset using Jimeng"

Claude: [Automatically invokes the skill, generates images, and saves to /pic directory]

For more details, see jimeng2api/Skill.md.

📖 API Documentation

Asynchronous Task Flow

Image and video generation endpoints are asynchronous. A POST request only submits a task and returns immediately; it does not contain the generated image or video URLs. Poll the task endpoint until the status becomes succeeded, then read result or call the result endpoint.

# 1. Submit a generation task
curl -X POST http://localhost:5100/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  -d '{"model":"jimeng-4.5","prompt":"A cute little cat"}'

# 2. Poll task status
curl http://localhost:5100/v1/tasks/task_xxxxx

# 3. Fetch final result after status is succeeded
curl http://localhost:5100/v1/tasks/task_xxxxx/result

Task response:

{
  "id": "task_550e8400-e29b-41d4-a716-446655440000",
  "object": "task",
  "type": "image_generation",
  "status": "queued",
  "created": 1703123456,
  "updated": 1703123456,
  "result_url": "/v1/tasks/task_550e8400-e29b-41d4-a716-446655440000"
}

Task statuses: queued, running, succeeded, failed.

Final image result example:

{
  "created": 1703123456,
  "data": [
    {
      "url": "https://p3-sign.toutiaoimg.com/tos-cn-i-tb4s082cfz/abc123.webp"
    }
  ]
}

Text-to-Image

POST /v1/images/generations

Request Parameters:

• model (string, optional): The name of the model to use. Defaults to jimeng-4.5 on all sites (China/US/HK/JP/SG).
• prompt (string): The text description of the image.
• ratio (string, optional): The aspect ratio of the image, defaults to "1:1". Supported ratios: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9. Note: When intelligent_ratio is true, this parameter will be ignored and the system will automatically infer the optimal ratio from the prompt.
• resolution (string, optional): The resolution level, defaults to "2k". Supported resolutions: 1k, 2k, 4k.
• intelligent_ratio (boolean, optional): Whether to enable intelligent ratio, defaults to false. ⚠️ This parameter only works for the jimeng-4.0/jimeng-4.1/jimeng-4.5/jimeng-4.6/jimeng-5.0 model; other models will ignore it. When enabled, the system automatically infers the optimal image ratio from the prompt (e.g., "portrait" → 9:16, "landscape" → 16:9).
• negative_prompt (string, optional): Negative prompt.
• sample_strength (number, optional): Sampling strength (0.0-1.0).
• response_format (string, optional): Final task result format ("url"(default) or "b64_json"). The submit response is always a task object.

# Default parameters (ratio: "1:1", resolution: "2k")
curl -X POST http://localhost:5100/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  -d \
    "{\"model\": \"jimeng-4.5\", \"prompt\": \"A cute little cat\"}"

# Example using 4K resolution
curl -X POST http://localhost:5100/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  -d \
    "{\"model\": \"jimeng-4.5\", \"prompt\": \"Magnificent landscape, ultra-high resolution\", \"ratio\": \"16:9\", \"resolution\": \"4k\"}"

# Example using intelligent ratio (system will infer 9:16 from "portrait")
curl -X POST http://localhost:5100/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  -d \
    "{\"model\": \"jimeng-4.5\", \"prompt\": \"A running lion, portrait orientation\", \"resolution\": \"2k\", \"intelligent_ratio\": true}"

Supported Models:

• nanobananapro: International sites only, supports ratio and resolution.
• nanobanana: International sites only.
• jimeng-5.0: China and Asia international sites (HK/JP/SG).
• jimeng-4.6: China and Asia international sites (HK/JP/SG).
• jimeng-4.5: Works on all sites, supports all 2k/4k ratios and intelligent_ratio. (Default for all sites)
• jimeng-4.1: Works on all sites, supports all 2k/4k ratios and intelligent_ratio.
• jimeng-4.0: Works on all sites.
• jimeng-3.1: China site only.
• jimeng-3.0: Works on all sites.

Unsupported or region-incompatible models now return 400 invalid_request_error instead of silently falling back to the default model.

Supported Ratios and Corresponding Resolutions:

resolution	ratio	Resolution
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
	4:3	2304×1728
	3:4	1728×2304
	16:9	2560×1440
	9:16	1440×2560
	3:2	2496×1664
	2:3	1664×2496
	21:9	3024×1296
4k	1:1	4096×4096
	4:3	4608×3456
	3:4	3456×4608
	16:9	5120×2880
	9:16	2880×5120
	3:2	4992×3328
	2:3	3328×4992
	21:9	6048×2592

Image-to-Image

POST /v1/images/compositions

Generate a new image based on one or more input images, combined with a text prompt. Supports creative modes like image blending, style transfer, and content synthesis.

# International site image-to-image example (local file upload)
# US site uses "us-YOUR_SESSION_ID"
# Hong Kong site uses "hk-YOUR_SESSION_ID"
# Japan site uses "jp-YOUR_SESSION_ID"
curl -X POST http://localhost:5100/v1/images/compositions \
  -H "Authorization: Bearer us-YOUR_SESSION_ID" \
  -F "prompt=A cute cat, anime style" \
  -F "model=jimeng-4.5" \
  -F "images=@/path/to/your/local/cat.jpg"

Request Parameters:

• model (string, optional): The name of the model to use. Defaults to jimeng-4.5 on all sites (China/US/HK/JP/SG).
• prompt (string): Text description of the image to guide the generation.
• images (array): An array of input images.
• ratio (string, optional): The aspect ratio of the image, defaults to "1:1". Supported ratios: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9.
• resolution (string, optional): The resolution level, defaults to "2k". Supported resolutions: 1k, 2k, 4k.
• intelligent_ratio (boolean, optional): Whether to enable intelligent ratio, defaults to false. ⚠️ This parameter only works for the jimeng-4.0/jimeng-4.1/jimeng-4.5 model; other models will ignore it. When enabled, the system automatically adjusts the output ratio based on the prompt and input images.
• negative_prompt (string, optional): Negative prompt.
• sample_strength (number, optional): Sampling strength (0.0-1.0).
• response_format (string, optional): Final task result format ("url"(default) or "b64_json"). The submit response is always a task object.

Limits:

• Number of input images: 1-10
• Supported image formats: Common formats (JPG, PNG, WebP, etc.).
• Image size limit: Recommended not to exceed 100MB per image.
• Generation time: Typically 30 seconds to 5 minutes; complex compositions may take longer.

Usage Examples:

# Example 1: URL image style transfer (using application/json)
curl -X POST http://localhost:5100/v1/images/compositions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  -d \
    "{\"model\": \"jimeng-4.5\", \"prompt\": \"Convert this photo into an oil painting style, with vibrant colors and distinct brushstrokes\", \"images\": [\"https://example.com/photo.jpg\"], \"ratio\": \"1:1\", \"resolution\": \"2k\", \"sample_strength\": 0.7}"

# Example 2: Local single file upload (using multipart/form-data)
curl -X POST http://localhost:5100/v1/images/compositions \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  -F "prompt=A cute cat, anime style" \
  -F "model=jimeng-4.5" \
  -F "ratio=1:1" \
  -F "resolution=1k" \
  -F "images=@/path/to/your/local/cat.jpg"

# Example 3: Local multiple file upload (using multipart/form-data)
curl -X POST http://localhost:5100/v1/images/compositions \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  -F "prompt=Merge these two images" \
  -F "model=jimeng-4.5" \
  -F "images=@/path/to/your/image1.jpg" \
  -F "images=@/path/to/your/image2.png"

Submit Response Example (applies to all examples above):

{
  "id": "task_550e8400-e29b-41d4-a716-446655440000",
  "object": "task",
  "type": "image_composition",
  "status": "queued",
  "created": 1703123456,
  "updated": 1703123456,
  "result_url": "/v1/tasks/task_550e8400-e29b-41d4-a716-446655440000"
}

Use GET /v1/tasks/{id} or GET /v1/tasks/{id}/result to retrieve the final data after the task succeeds.

❓ FAQ & Solutions

Q: What if my upload fails? A: Make sure the image URL is reachable, the format is supported, and the file size is under 100MB.

Q: What if generation takes too long? A: Check GET /v1/tasks/{id}. Complex multi-image compositions can stay running for several minutes. If the task becomes failed, inspect its error field and resubmit if needed.

Q: How to improve composition quality? A:

• Start with high-quality input images.
• Write clear, detailed prompts.
• Tune the sample_strength parameter.
• Avoid mixing too many conflicting styles.

Q: What image formats are supported? A: Common formats (JPG, PNG, WebP, GIF) work. JPG or PNG is recommended.

Q: Can I use local images? A: Yes—direct local file upload is supported. See the "Local single file upload" example above. You can also keep using image URLs.

Video Generation

POST /v1/videos/generations

Generate a video from a text prompt (Text-to-Video) or from start/end frame images (Image-to-Video). Supports four generation modes:

1. Text-to-Video: Pure text prompt without any images
2. Image-to-Video: Single image as the first frame
3. First-Last Frame: Two images as the first and last frames
4. Omni Reference (New): Supports pure text prompts or optional mixed image/video reference materials. When materials are provided, use @field_name references in the prompt to describe each material's role. Supported by Seedance 2.0, Seedance 2.0 Fast, and their VIP variants.

Mode Detection: The system automatically determines the generation mode based on the presence of images:

• No images → Text-to-Video mode
• 1 image → Image-to-Video mode (only first_frame_image is provided)
• 2 images → First-Last Frame mode (both first_frame_image and end_frame_image are provided)
• functionMode=omni_reference → Omni Reference mode (requires explicit parameter)

Request Parameters:

• model (string): The name of the video model to use.
• prompt (string): The text description of the video content.
• ratio (string, optional): Video aspect ratio, defaults to "1:1". Supported ratios: 1:1, 4:3, 3:4, 16:9, 9:16, 21:9. Note: In image-to-video mode (when images are provided), this parameter will be ignored, and the video aspect ratio will be determined by the input image's actual ratio.
• resolution (string, optional): Video resolution, defaults to "720p". Supported resolutions: 720p, 1080p. Note: Only jimeng-video-3.0 and jimeng-video-3.0-fast support this parameter; other models ignore it.
• duration (number, optional): Video duration in seconds. Supported values vary by model:
  • jimeng-video-veo3 / jimeng-video-veo3.1: 8 (fixed)
  • jimeng-video-sora2: 4 (default), 8, 12
  • jimeng-video-seedance-2.0 / jimeng-video-seedance-2.0-fast / VIP variants: 4~15 (any integer second, default 5)
  • jimeng-video-3.5-pro: 5 (default), 10, 12
  • Other models: 5 (default), 10
• file_paths (array, optional): An array of image URLs to specify the start frame (1st element) and end frame (2nd element) of the video.
• [file] (file, optional): Local image files uploaded via multipart/form-data (up to 2) to specify the start frame and end frame. The field name can be arbitrary, e.g., image1.
• functionMode (string, optional): Generation mode. Defaults to "first_last_frames". Supported values:
  • "first_last_frames" (default): Standard mode, auto-detects text-to-video / image-to-video / first-last-frame based on image count.
  • "omni_reference": Omni Reference mode. Supports jimeng-video-seedance-2.0, jimeng-video-seedance-2.0-fast, jimeng-video-seedance-2.0-vip, and jimeng-video-seedance-2.0-fast-vip. Reference materials are optional; when provided, upload files with specific field names: image_file_1 ~ image_file_9 (images), video_file_1 ~ video_file_3 (videos). Both local files and URLs are supported. Use @field_name in the prompt to reference materials.
• response_format (string, optional): Final task result format, supports url (default) or b64_json. The submit response is always a task object.

Image Input Description:

• You can provide input images via file_paths (URL array) or by directly uploading files.
• If both methods are provided, the system will prioritize the locally uploaded files.
• Up to 2 images are supported, the 1st as the start frame, the 2nd as the end frame.
• Important: Once image input is provided (image-to-video or first-last frame video), the ratio parameter will be ignored, and the video aspect ratio will be determined by the input image's actual ratio. The resolution parameter remains effective.

Omni Reference Mode (New):

• Requires functionMode=omni_reference and a supported Seedance 2.0 model: jimeng-video-seedance-2.0, jimeng-video-seedance-2.0-fast, jimeng-video-seedance-2.0-vip, or jimeng-video-seedance-2.0-fast-vip.
• Reference materials are optional. If no image/video material is provided, Omni Reference mode falls back to text-only generation with the selected Seedance model.
• Material Limits:
  • Up to 9 images (image_file_1 ~ image_file_9)
  • Up to 3 videos (video_file_1 ~ video_file_3)
  • Total materials (images + videos) ≤ 12
  • Total video duration ≤ 15 seconds
• Image inputs support three methods (priority from high to low):
  1. Local file upload: multipart/form-data with field names image_file_1 ~ image_file_9 (e.g., curl -F "image_file_1=@local.jpg")
  2. URL in form field: Same field names but with a URL string instead of a file (e.g., curl -F "image_file_1=https://...", no @ prefix). The server downloads the image first, then uploads it.
  3. file_paths/filePaths array: URL array in JSON body, mapped to image_file_1/image_file_2... slots in order.
• All three methods can be mixed freely — each slot is filled by the highest-priority source available.
• Video input supports two methods (priority from high to low):
  1. Local file upload: multipart/form-data with field name video_file_1 ~ video_file_3 (e.g., curl -F "video_file_1=@local.mp4")
  2. URL in form field: Same field name but with a URL string instead of a file (e.g., curl -F "video_file_1=https://...", no @ prefix). The server downloads the video first, then uploads it.
• Reference materials are optional; if provided, up to 12 files total are supported.
• In the prompt, use @field_name (e.g., @image_file_1, @video_file_1) or @original_filename to reference materials and describe their roles.
• Note: When using curl -F, the @ symbol in prompt values is interpreted as a file reference. Use --form-string for the prompt field instead.
• Example prompt: "@image_file_1 as first frame, @image_file_2 as last frame, mimic motion from @video_file_1"

Supported Video Models:

• jimeng-video-seedance-2.0-vip - Seedance 2.0 VIP channel, China site only, supports 4~15s duration, supports Omni Reference mode
• jimeng-video-seedance-2.0-fast-vip - Seedance 2.0 Fast VIP channel, China site only, supports 4~15s duration, supports Omni Reference mode
• jimeng-video-seedance-2.0 - Seedance 2.0, China site only, supports 4~15s duration, supports Omni Reference mode (Latest)
• jimeng-video-seedance-2.0-fast - Seedance 2.0 Fast, China site only, supports 4~15s duration, supports Omni Reference mode, faster generation speed
• jimeng-video-3.5-pro - Professional Edition v3.5, works on all sites (Default)
• jimeng-video-veo3 - Veo3 model, Asia international sites only (HK/JP/SG), fixed 8s duration
• jimeng-video-veo3.1 - Veo3.1 model, Asia international sites only (HK/JP/SG), fixed 8s duration
• jimeng-video-sora2 - Sora2 model, Asia international sites only (HK/JP/SG)
• jimeng-video-3.0-pro - Professional Edition, China and Asia international sites (HK/JP/SG)
• jimeng-video-3.0 - Standard Edition, works on all sites
• jimeng-video-3.0-fast - Fast Edition, China and Asia international sites (HK/JP/SG)
• jimeng-video-2.0-pro - Professional Edition v2, China and Asia international sites (HK/JP/SG)
• jimeng-video-2.0 - Standard Edition v2, China and Asia international sites (HK/JP/SG)

Note: US site only supports jimeng-video-3.5-pro and jimeng-video-3.0 models.

Usage Examples:

# Example 1: Text-to-Video (0 images) - Pure text generation
curl -X POST http://localhost:5100/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  -d \
    "{\"model\": \"jimeng-video-3.0\", \"prompt\": \"A lion running on the grassland\", \"ratio\": \"16:9\", \"resolution\": \"1080p\", \"duration\": 10}"

# Example 2: Image-to-Video (1 image) - Single image as first frame
curl -X POST http://localhost:5100/v1/videos/generations \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  -F "prompt=A man is talking" \
  -F "model=jimeng-video-3.0" \
  -F "ratio=9:16" \
  -F "duration=5" \
  -F "image_file_1=@/path/to/your/first-frame.png"

# Example 3: First-Last Frame (2 images) - Two images as first and last frames
curl -X POST http://localhost:5100/v1/videos/generations \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  -F "prompt=Smooth transition between scenes" \
  -F "model=jimeng-video-3.0" \
  -F "ratio=16:9" \
  -F "duration=10" \
  -F "image_file_1=@/path/to/first-frame.png" \
  -F "image_file_2=@/path/to/last-frame.png"

# Example 4: Image-to-Video with URL image
curl -X POST http://localhost:5100/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  -d \
    "{\"model\": \"jimeng-video-3.0\", \"prompt\": \"A woman dancing in a garden\", \"ratio\": \"4:3\", \"duration\": 10, \"filePaths\": [\"https://example.com/your-image.jpg\"]}"

# Example 5: Omni Reference mode - all local files
# Requires a Seedance 2.0 model. For VIP channel, replace model with
# jimeng-video-seedance-2.0-vip or jimeng-video-seedance-2.0-fast-vip.
# Note: Use --form-string for prompt containing @ references (curl -F interprets @ as file)
curl -X POST http://localhost:5100/v1/videos/generations \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  --form-string "prompt=@image_file_1 as first frame, @image_file_2 as last frame, mimic motion from @video_file" \
  -F "model=jimeng-video-seedance-2.0" \
  -F "functionMode=omni_reference" \
  -F "ratio=16:9" \
  -F "duration=5" \
  -F "image_file_1=@/path/to/first.png" \
  -F "image_file_2=@/path/to/second.png" \
  -F "video_file=@/path/to/reference-video.mp4"

# Example 6: Omni Reference mode - mix URL images + local video
# image_file_1/image_file_2 use URLs (no @ prefix), video_file uses local file (with @ prefix)
curl -X POST http://localhost:5100/v1/videos/generations \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  --form-string "prompt=@image_file_1 as first frame, @image_file_2 as last frame, mimic motion from @video_file" \
  -F "model=jimeng-video-seedance-2.0" \
  -F "functionMode=omni_reference" \
  -F "ratio=16:9" \
  -F "duration=5" \
  -F "image_file_1=https://example.com/first.jpg" \
  -F "image_file_2=https://example.com/second.jpg" \
  -F "video_file=@/path/to/reference-video.mp4"

# Example 7: Omni Reference mode - all materials via URL (no local files needed)
# image_file_1/image_file_2/video_file all use URLs (no @ prefix)
curl -X POST http://localhost:5100/v1/videos/generations \
  -H "Authorization: Bearer YOUR_SESSION_ID" \
  --form-string "prompt=@image_file_1 as first frame, @image_file_2 as last frame, mimic motion from @video_file" \
  -F "model=jimeng-video-seedance-2.0" \
  -F "functionMode=omni_reference" \
  -F "ratio=16:9" \
  -F "duration=5" \
  -F "image_file_1=https://example.com/first.jpg" \
  -F "image_file_2=https://example.com/second.jpg" \
  -F "video_file=https://example.com/reference-video.mp4"

Each video example returns a task object. Poll GET /v1/tasks/{id} until status is succeeded, then read result.data[0].url or call GET /v1/tasks/{id}/result.

Token API

Token Bound Proxy Feature (New)

Description: Users can embed a proxy URL in the token to solve issues where IP restrictions lead to 0 credit points during check-in. Each account can be bound to an independent proxy.

Token Format:

[ProxyURL@][RegionPrefix-]session_id

The proxy prefix is at the outermost layer, and the region prefix follows the session_id.

Supported Proxy Protocols:

• HTTP Proxy: http://host:port
• HTTPS Proxy: https://host:port
• SOCKS4 Proxy: socks4://host:port
• SOCKS5 Proxy: socks5://host:port
• Authenticated Proxy: http://user:pass@host:port

Full Examples:

Scenario	Token Format
China site, no proxy	session_id_xxx
US site, no proxy	us-session_id_xxx
HK site, no proxy	hk-session_id_xxx
China site + SOCKS5 Proxy	socks5://127.0.0.1:1080@session_id_xxx
US site + HTTP Proxy	http://127.0.0.1:7890@us-session_id_xxx
HK site + Auth Proxy	http://user:pass@proxy.com:8080@hk-session_id_xxx

API Call Examples:

# Single token with proxy
curl -X POST http://localhost:5100/v1/images/generations \
  -H "Authorization: Bearer socks5://127.0.0.1:1080@us-session_id" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a cat", "model": "jimeng-3.0"}'

# Multiple tokens, some with proxy
curl -X POST http://localhost:5100/token/receive \
  -H "Authorization: Bearer socks5://1.2.3.4:1080@us-token1,http://5.6.7.8:8080@hk-token2,token3"

Backward Compatibility: The token format without a proxy is fully compatible and requires no changes.

Check Token Status

POST /token/check

Check if a token is valid and active.

Request Parameters:

• token (string): The session token to check

Response Format:

{
  "live": true
}

Get Credit Points

POST /token/points

Get the current credit balance for one or more tokens.

Request Headers:

• Authorization: Bearer token(s), multiple tokens separated by commas

Response Format:

[
  {
    "token": "your_token",
    "points": {
      "giftCredit": 10,
      "purchaseCredit": 0,
      "vipCredit": 0,
      "totalCredit": 10
    }
  }
]

Receive Daily Credits

POST /token/receive

Manually trigger daily credit collection (check-in). Attempts to claim credits and returns the latest credit information regardless of claim success.

Request Headers:

• Authorization: Bearer token(s), multiple tokens separated by commas

Response Format:

[
  {
    "token": "your_token",
    "credits": {
      "giftCredit": 10,
      "purchaseCredit": 0,
      "vipCredit": 0,
      "totalCredit": 10
    },
    "received": true,
    "error": "optional error message"
  }
]

Response Fields:

• token (string): The token that was processed
• credits (object): Current credit balance after operation
• received (boolean): Whether credits were successfully claimed (true if claimed, false if already had credits or claim failed)
• error (string, optional): Error message if claim failed

Usage Example:

# Single token
curl -X POST http://localhost:5100/token/receive \
  -H "Authorization: Bearer YOUR_SESSION_ID"

# Multiple tokens
curl -X POST http://localhost:5100/token/receive \
  -H "Authorization: Bearer TOKEN1,TOKEN2,TOKEN3"

🔍 API Response Format

Generation Task Submit Response

{
  "id": "task_550e8400-e29b-41d4-a716-446655440000",
  "object": "task",
  "type": "image_generation",
  "status": "queued",
  "created": 1759058768,
  "updated": 1759058768,
  "result_url": "/v1/tasks/task_550e8400-e29b-41d4-a716-446655440000"
}

Final Result After Task Succeeds

{
  "created": 1759058800,
  "data": [
    {
      "url": "https://example.com/image1.jpg"
    },
    {
      "url": "https://example.com/image2.jpg"
    }
  ]
}

🏗️ Project Architecture

jimeng2api/
├── src/
│   ├── api/
│   │   ├── builders/             # Request builders
│   │   │   └── payload-builder.ts  # API request payload builder
│   │   ├── controllers/          # Controller layer
│   │   │   ├── core.ts           # Core functions (network requests, file handling)
│   │   │   ├── images.ts         # Image generation logic
│   │   │   └── videos.ts         # Video generation logic
│   │   ├── routes/               # Route definitions
│   │   │   ├── index.ts          # Route entry
│   │   │   ├── images.ts         # Image generation routes
│   │   │   ├── videos.ts         # Video generation routes
│   │   │   ├── token.ts          # Token management routes
│   │   │   ├── models.ts         # Model list routes
│   │   │   └── ping.ts           # Health check routes
│   │   └── consts/               # Constant definitions
│   │       ├── common.ts         # Common constants
│   │       ├── dreamina.ts       # Dreamina site constants
│   │       └── exceptions.ts     # Exception constants
│   ├── lib/                      # Core library
│   │   ├── configs/              # Configuration loading
│   │   │   ├── service-config.ts # Service configuration
│   │   │   └── system-config.ts  # System configuration
│   │   ├── consts/               # Constants
│   │   ├── exceptions/           # Exception classes
│   │   │   ├── Exception.ts      # Base exception
│   │   │   └── APIException.ts   # API exception
│   │   ├── request/              # Request handling
│   │   │   └── Request.ts        # Request wrapper
│   │   ├── response/             # Response handling
│   │   │   ├── Response.ts       # Response wrapper
│   │   │   ├── Body.ts           # Response body base
│   │   │   ├── SuccessfulBody.ts # Success response body
│   │   │   └── FailureBody.ts    # Failure response body
│   │   ├── config.ts             # Configuration center
│   │   ├── server.ts             # Server core
│   │   ├── logger.ts             # Logger
│   │   ├── error-handler.ts      # Unified error handling
│   │   ├── jobs/                 # Async task queue
│   │   ├── smart-poller.ts       # Smart poller
│   │   ├── aws-signature.ts      # AWS signature
│   │   ├── environment.ts        # Environment variables
│   │   ├── initialize.ts         # Initialization logic
│   │   ├── http-status-codes.ts  # HTTP status code constants
│   │   ├── image-uploader.ts     # Image upload utility
│   │   ├── image-utils.ts        # Image processing utility
│   │   ├── region-utils.ts       # Region handling utility
│   │   ├── video-uploader.ts     # Video upload utility (VOD)
│   │   └── util.ts               # Common utility functions
│   └── index.ts                  # Entry file
├── configs/                      # Configuration files
├── Dockerfile                    # Docker configuration
└── package.json                  # Project configuration

🔧 Core Components

TaskManager

• Generation APIs return a task ID immediately.
• Background workers run Jimeng generation and upstream polling.
• Clients query /v1/tasks/{id} for task status and final results.

SmartPoller

• Background workers adapt upstream polling interval based on status codes.
• Multiple exit conditions to avoid invalid waiting.
• Detailed progress tracking and logging.

Unified ErrorHandler

• Categorized error handling (network errors, API errors, timeouts, etc.).
• Automatic retry mechanism.
• User-friendly error messages.

Safe JSON Parsing

• Automatically fixes common JSON format issues.
• Supports trailing commas and single quotes.
• Detailed parsing error logs.

⚙️ Advanced Configuration

Background Polling Configuration

export const POLLING_CONFIG = {
  MAX_POLL_COUNT: 900,    // Max polling attempts (15 minutes)
  POLL_INTERVAL: 5000,    // Base polling interval (5 second)
  STABLE_ROUNDS: 5,       // Stable rounds
  TIMEOUT_SECONDS: 900    // Timeout (15 minutes)
};

Retry Configuration

export const RETRY_CONFIG = {
  MAX_RETRY_COUNT: 3,     // Max retry attempts
  RETRY_DELAY: 5000       // Retry delay (5 seconds)
};

🐛 Troubleshooting

Common Issues

1. JSON Parsing Error

   • Make sure your request body is valid.
   • The system will automatically fix common format issues.

2. Invalid sessionid

   • Get a fresh sessionid from the appropriate site.
   • Check if the sessionid format is correct.

3. Generation Takes Too Long

   • Submit endpoints return a task immediately.
   • Poll GET /v1/tasks/{id} to check queued, running, succeeded, or failed.
   • If the task fails or times out, the task response includes an error field.

4. Insufficient Credits

   • Go to the Jimeng/Dreamina official website to check your credit balance.
   • The API returns detailed credit info.

🙏 Acknowledgements

This project is based on the contributions and inspiration of the following open-source project:

• jimeng-api - Thanks to this project for providing an important reference and technical basis for the reverse engineering of the Jimeng API. This project has improved its functionality and architecture based on it.

📄 License

GPL v3 License - see the LICENSE file for details.

⚠️ Disclaimer

This project is for learning and research purposes only. Please comply with relevant service terms and laws. Any consequences arising from the use of this project are the sole responsibility of the user.