Doubao Image & Video Generation

The scripts read the API key from the ARK_API_KEY environment variable. If not set, they fall back to a built-in default key.

You can also pass --api-key and --base-url as CLI arguments to override.

Default base URL: https://ark.cn-beijing.volces.com/api/v3

Image Generation (Seedream)

When to Use

• User wants to generate an image from a text description
• User wants to create game sprites, concept art, icons, character designs
• User wants to transform or blend reference images into a new image
• User says "生成图片", "画一张", "create an image", etc.

How to Run

uv run <skill-path>/scripts/generate_image.py \
  --prompt "a cute orange cat sitting on a wooden barrel, pixel art style" \
  --output ./output.png

Parameters

Size Options by Version

Examples

Basic text-to-image:

uv run scripts/generate_image.py \
  --prompt "a post-apocalyptic vehicle driving through desert ruins, dramatic lighting" \
  --output ./vehicle_concept.png \
  --size 2K

Game sprite generation:

uv run scripts/generate_image.py \
  --prompt "top-down 2D game sprite of a rusty armored truck, pixel art, 64x64, transparent background" \
  --output ./sprite_truck.png \
  --version 5.0 \
  --size 2K

Image-to-image with reference:

uv run scripts/generate_image.py \
  --prompt "same style but in winter setting with snow" \
  --image "https://example.com/reference.png" \
  --output ./winter_version.png

Multiple reference images (style fusion):

uv run scripts/generate_image.py \
  --prompt "combine these styles into a new character design" \
  --image "https://example.com/style1.png" \
  --image "https://example.com/style2.png" \
  --output ./fused_design.png

Transparent game sprite (background removal):

uv run scripts/generate_image.py \
  --prompt "a warrior character holding a sword, game sprite, white background" \
  --remove-bg \
  --output ./warrior_sprite.png

Batch generation with seed:

uv run scripts/generate_image.py \
  --prompt "a sci-fi weapon icon, game UI, clean design" \
  -n 4 \
  --seed 42 \
  --version 4.5 \
  --output ./weapon_icon.png
# Outputs: weapon_icon_1.png, weapon_icon_2.png, weapon_icon_3.png, weapon_icon_4.png

Transparent PNG (Background Removal)

The Seedream API always outputs JPEG — there is no native transparency support. When you include "transparent background" in the prompt, the API renders a checkerboard pattern (simulating transparency visually), but the image is still opaque RGB JPEG.

To produce true RGBA PNG with an alpha channel, use the --remove-bg flag:

uv run scripts/generate_image.py \
  --prompt "a cute robot character, game sprite, white background" \
  --remove-bg \
  --output ./robot.png

How it works:

1. Seedream generates the image as usual (JPEG)
2. rembg (AI background removal) strips the background and creates an alpha channel
3. The result is saved as a true RGBA PNG file

Tips for best results:

• Include "white background" or "solid color background" in the prompt — this gives rembg a cleaner edge to detect
• Avoid "transparent background" in the prompt (it creates checkerboard patterns that confuse rembg)
• Works best for isolated subjects: characters, items, sprites, icons
• First run may be slow (~30s extra) as rembg downloads its model (~180MB)

Dependencies: --remove-bg requires rembg and pillow (auto-installed by uv run via inline script metadata).

Output

The script prints a JSON summary on success:

{
  "status": "success",
  "file": "./output.png",
  "size": "3136x1344",
  "model": "doubao-seedream-4-5-251128",
  "tokens_used": 4197376
}

On error, it prints a JSON error and exits with code 1:

{
  "status": "error",
  "error": "API returned 400: invalid size for model version 4.5"
}

Video Generation (Seedance)

When to Use

• User wants to generate a video from a text prompt
• User wants to animate a still image (image-to-video)
• User says "生成视频", "做一个动画", "create a video", "animate this", etc.

How to Run

Video generation is asynchronous — it takes 1-5 minutes. The workflow is:

1. Submit the task with generate_video.py → get a task_id
2. Poll the status with get_video_task_status.py → get the video URL when done

# Step 1: Submit
uv run <skill-path>/scripts/generate_video.py \
  --prompt "a rusted vehicle driving through a sandstorm" \
  --output ./video_output.mp4

# Step 2: Check status (the task_id is printed by step 1)
uv run <skill-path>/scripts/get_video_task_status.py \
  --task-id "task_abc123" \
  --output ./video_output.mp4

Parameters for generate_video.py

Parameters for get_video_task_status.py

Available Models

Examples

Text-to-video:

uv run scripts/generate_video.py \
  --prompt "a convoy of armored vehicles crossing a desert, dust clouds, cinematic" \
  --duration 5 \
  --ratio 16:9 \
  --output ./convoy.mp4

Image-to-video (animate a still):

uv run scripts/generate_video.py \
  --prompt "the vehicle starts moving forward, dust kicks up" \
  --first-frame "https://example.com/vehicle_still.png" \
  --output ./vehicle_moving.mp4

Poll with auto-wait:

uv run scripts/get_video_task_status.py \
  --task-id "task_abc123" \
  --output ./convoy.mp4 \
  --wait

Output

generate_video.py prints:

{
  "status": "submitted",
  "task_id": "task_abc123",
  "model": "doubao-seedance-1-5-pro-251215",
  "message": "Video generation started. Use get_video_task_status.py --task-id task_abc123 --wait to check."
}

get_video_task_status.py prints:

{
  "status": "succeeded",
  "task_id": "task_abc123",
  "video_url": "https://...",
  "file": "./convoy.mp4"
}

Or if still processing:

{
  "status": "processing",
  "task_id": "task_abc123",
  "message": "Still generating..."
}

Prompting Tips

1. Be descriptive — Seedream and Seedance respond well to detailed prompts with style, lighting, and composition details.
2. Language — Both Chinese and English work. For game assets, English tends to yield more consistent pixel art / game art styles.
3. Game sprites — Include keywords like "pixel art", "game sprite", "top-down", "side-view", specific pixel dimensions. Use --remove-bg for transparent sprites.
4. Transparent images — Use --remove-bg flag + "white background" or "solid color background" in the prompt. Do NOT say "transparent background" (causes checkerboard artifacts).
5. Video — Describe motion explicitly: "the camera slowly pans left", "the character walks forward".
6. Aspect ratios — For game assets, square (1:1) or landscape (16:9) work best. For character sprites, try portrait images then crop.
7. Batch generation — Use -n 4 to get multiple variations at once (Seedream 4.x only). Add --seed for reproducibility.

Error Handling

All scripts exit with code 0 on success, 1 on error. Errors are printed as JSON to stdout for easy parsing. Common issues:

• Invalid size for version: Check the size table above
• API key invalid: Verify ARK_API_KEY is set correctly
• Rate limited: Wait a moment and retry
• Video task failed: Re-submit with a simpler prompt or different model