AI Image Generator

异步生成 AI 图片与视频的技能。

⚠️ 首次使用必读

1. 获取 API Key

访问 https://ai.deepsop.com/ 注册并登录，然后创建你的 API Key。

2. 设置环境变量

在使用前，你必须先设置自己的 API Key：

# Linux/macOS/Git Bash (Windows)
export AI_ARTIST_TOKEN="sk-your_api_key_here"

# Windows PowerShell
$env:AI_ARTIST_TOKEN="sk-your_api_key_here"

3. 验证配置

验证配置是否正确：

python3 scripts/test_config.py

详细配置说明请查看下方"环境配置"章节。

快速开始

# 图片生成（默认 DeepSop·3.1Nano2-Evo）
python3 scripts/generate_image.py "一只可爱的猫"

# 视频生成（默认 DeepSop·V3.1FB）
python3 scripts/generate_video.py "海边日落风景"

参考图/视频上传流程

当用户提供本地文件作为参考图或参考视频时，需要先调用文件上传 API 转换为可访问的 URL：

文件上传 API

curl --location --request POST 'https://ai.deepsop.com/prod-api/system/fileUpload/upload' \
--header 'x-api-key: sk-your_api_key_here' \
--form 'file=@"C:\\Users\\admin\\Downloads\\image.png"'

返回结果：

{
  "msg": "操作成功",
  "fileName": "image.png",
  "code": 200,
  "url": "https://kocgo-ai-sales-test.oss-cn-hangzhou.aliyuncs.com/material/100/xxx.png"
}

使用上传后的 URL

获取到 url 后，可作为 firstImageUrl、lastImageUrl、imageUrlList、videoUrlList 或 elementList 等参数传入生成接口。

在对话中直接返回图片/视频

方式 1: Markdown 语法（推荐）

生成图片后，直接在回复中使用 Markdown 语法：

![图片描述](图片URL)
![视频描述](视频URL)

平台支持情况：

• ✅ WebChat、Discord、Telegram：完全支持
• ✅ 飞书：支持（需公开 URL）
• ❌ WhatsApp：不支持

方式 2: 下载后发送（需要 message 工具）

使用 --download 参数下载媒体文件，然后通过 message 工具发送：

python3 scripts/generate_image.py "风景画" --download
python3 scripts/generate_video.py "海边" --download

比如图片生成接着在代码中读取图片并发送：

from scripts.generate_image import generate_image
import base64

result = generate_image(prompt="风景画", download=True)

if result and result["status"] == "SUCCESS":
    # 方式 A: 使用 data URI
    image_uri = result["data_uri"]  # data:image/png;base64,...
    
    # 方式 B: 读取本地文件
    with open(result["local_path"], "rb") as f:
        image_data = f.read()
        base64_data = base64.b64encode(image_data).decode()

参数说明

通用参数

图片专属参数

视频专属参数

支持的模型

图片模型

| 模型 | methodType | 支持质量 | 支持比例 | 联网搜索 | 特点 | |------|-----------|---------|------| | S4.5 | 0 | 2K, 4K | 除 auto 外所有比例 | ❌ | 电影级画质4K，角色一致性 | N1 | 1 | 1K | 除 21:9、4:5、5:4、1:4、4:1、1:8、8:1 外 | ❌ | 支持多模态输入，精细参数调节 | N2 | 2 | 1K, 2K, 4K | 所有比例 | ❌ | 卓越的文字渲染和角色一致性 | N2-147 | 3 | 1K, 2K, 4K | 除 auto、1:4、4:1、1:8、8:1 外 | ❌ | 147版本，支持多模态输入 | S5.0L | 4 | 2K, 3K | 除 auto 外所有比例 | ✅ | 默认模型，生成快、风格全、易用 | N2-Pro | 5 | 1K, 2K, 4K | 除 auto、1:4、4:1、1:8、8:1 外 | ✅ | Pro版本，画质细节更优 | W2.7 | 6 | 1K, 2K | 除 auto、21:9 外 | ❌ | 画质清晰，细节丰富 | W2.7Pro | 7 | 1K, 2K | 除 auto、21:9 外 | ❌ | 精准控图与风格迁移 | N2-Evo | 8 | 1K, 2K, 4K | 所有比例 | ✅ | Evo版本，卓越的文字渲染 | N2-Beta | 9 | 1K, 2K, 4K | 所有比例 | ❌ | Beta测试版 | Auto | auto | 2K 除 auto、1:4、4:1、1:8、8:1、21:9 外 | ❌ | 自动选择最佳模型

视频模型

VEO3.1 系列（V3.1FB、V3.1PB、V3.1Fast、V3.1Pro）共同说明：

WAN2.6 系列共同说明：

Kling V3 Omni 特有能力：

参数联动规则（自动处理）

图片质量按模型自动过滤

图片比例按模型自动过滤

视频生成类型按模型自动过滤

视频分辨率按模型自动过滤

视频比例按模型自动过滤

视频时长按模型自动配置

镜头模式按模型自动过滤

参数显隐逻辑（自动处理）

按模型显示的参数

按模型隐藏的参数

参数联动显隐（同模型下受其他参数影响）

使用示例

图片生成

# 基础用法 - 默认模型 DeepSop·3.1Nano2-Evo
python3 scripts/generate_image.py "一匹狼"

# 指定质量
python3 scripts/generate_image.py "风景画" --quality "4K"

# 指定比例
python3 scripts/generate_image.py "风景画" --ratio "16:9"

# 使用 N2 模型
python3 scripts/generate_image.py "生成一只狗" --model N2

# 使用 N2-Pro 并开启联网搜索
python3 scripts/generate_image.py "2024年流行的装修风格" --model N2-Pro --web-search

# 使用 W2.7Pro
python3 scripts/generate_image.py "山水画" --model W2.7Pro --quality "2K" --ratio "9:16"

# 使用 N2-Evo
python3 scripts/generate_image.py "赛博朋克城市" --model N2-Evo --quality "4K" --ratio "16:9"

# 下载图片到本地
python3 scripts/generate_image.py "风景画" --download

# 直接输出 Markdown 图片链接
python3 scripts/generate_image.py "一只可爱的猫" --markdown-output

# 使用参考图生成
python3 scripts/generate_image.py "基于这张图生成变体" --reference-image "./reference.png"

图片生成

# 基础用法 - 默认 DeepSop·V3.1FB
python3 scripts/generate_video.py "海边日落风景"

# 指定比例和分辨率
python3 scripts/generate_video.py "海边日落风景" --ratio "9:16" --resolution "1080p"

# 指定时长
python3 scripts/generate_video.py "一只猫在玩耍" --duration 5

# 专家模式
python3 scripts/generate_video.py "海边日落风景" --mode pro

# 首尾帧生视频
python3 scripts/generate_video.py "花朵绽放" --generation-type FIRST&LAST --first-image "./flower_start.jpg" --last-image "./flower_end.jpg"

# 参考图生视频
python3 scripts/generate_video.py "产品展示" --generation-type REFERENCE --image-url-list "https://example.com/product1.jpg,https://example.com/product2.jpg"

# 视频续写
python3 scripts/generate_video.py "继续这个视频" --generation-type CONTINUATION --first-clip "./my_video.mp4" --duration 5

# Veo3.1 系列 - 文生视频
python3 scripts/generate_video.py "现代轻奢吊灯" --model V3.1FB --ratio "16:9" --duration 8

# Veo3.1 系列 - 首尾帧控制
python3 scripts/generate_video.py "灯具变形动画" --model V3.1Pro --first-image "./start.jpg" --last-image "./end.jpg" --duration 8

# Veo3.1 系列 - 负向提示词
python3 scripts/generate_video.py "人物奔跑" --model V3.1Pro --negative-prompt "模糊, 抖动" --duration 8

# Veo3.1Fast - 生成多个视频
python3 scripts/generate_video.py "产品广告" --model V3.1Fast --n 3 --duration 4

# W2.7t - 文生视频
python3 scripts/generate_video.py "现代轻奢吊灯宣传" --model W2.7t --ratio "16:9" --duration 10 --prompt-extend

# W2.7t - 带参考音频
python3 scripts/generate_video.py "产品展示" --model W2.7t --audio-url "https://example.com/audio.mp3" --duration 10

# W2.7i - 首帧图生视频
python3 scripts/generate_video.py "水晶灯展示" --model W2.7i --first-image "./lamp.jpg" --duration 8

# W2.7i - 视频续写
python3 scripts/generate_video.py "继续这个动画" --model W2.7i --first-image "./lamp.jpg" --first-clip "./lamp_animation.mp4" --duration 5

# W2.7r - 参考视频生视频
python3 scripts/generate_video.py "参考素材风格生成" --model W2.7r --video-url-list "https://example.com/video.mp4" --duration 10

# W2.7r - 多参考视频
python3 scripts/generate_video.py "风格迁移" --model W2.7r --video-url-list "https://example.com/style1.mp4,https://example.com/style2.mp4" --duration 8

# Kling V3 Omni - 多镜头分镜
python3 scripts/generate_video.py "电影预告片" --model "Kling V3 Omni" --shot-type multi --multi-shot --mode pro

# Kling V3 Omni - 参考主体
python3 scripts/generate_video.py "角色在行走" --model "Kling V3 Omni" --element-list "https://example.com/character.jpg"

# Kling V3 Omni - 保留原声的视频编辑
python3 scripts/generate_video.py "编辑这段视频" --model "Kling V3 Omni" --generation-type EDIT --first-clip "./original.mp4" --keep-original-sound

# Sora2 Pro - 高分辨率
python3 scripts/generate_video.py "风景大片" --model Sora2Pro --ratio "7:4" --resolution "2K" --duration 12

模型名称速查表

图片模型（methodType → 模型名称）

视频模型（methodType → 模型名称）

程序化调用

from scripts.generate_image import generate_image, generate_video

# 图片 - 默认 DeepSop·3.1Nano2-Evo
result = generate_image(prompt="一只可爱的猫咪")

# 图片 - N2 模型
result = generate_image(prompt="生成一只狗", model="N2")

# 图片 - 带联网搜索
result = generate_image(prompt="2024年流行的装修风格", model="N2-Pro", web_search=True)

# 图片 - 下载到本地
result = generate_image(prompt="风景画", model="S5.0L", download=True, output_dir="./images")

# 视频 - 默认 DeepSop·V3.1FB
result = generate_video(prompt="小骏马祝福大家新年快乐")

# 视频 - S1.5Pro 带音频
result = generate_video(
    prompt="海边日落风景",
    model="S1.5Pro",
    ratio="9:16",
    resolution="1080p",
    duration=5,
    generate_audio=True
)

# 视频 - V3.1Pro 首尾帧控制
result = generate_video(
    prompt="灯具变形动画",
    model="V3.1Pro",
    first_image_url="https://example.com/start.jpg",
    last_image_url="https://example.com/end.jpg",
    ratio="16:9",
    resolution="1080p",
    duration=8
)

# 视频 - V3.1Fast 生成多个
result = generate_video(
    prompt="产品广告",
    model="V3.1Fast",
    n=3,
    duration=4,
    person_generation="allow_adult"
)

# 视频 - W2.7t 带参考音频和提示词改写
result = generate_video(
    prompt="产品宣传片",
    model="W2.7t",
    ratio="16:9",
    resolution="1080p",
    duration=10,
    audio_url="https://example.com/music.mp3",
    prompt_extend=True
)

# 视频 - W2.7r 多参考视频
result = generate_video(
    prompt="风格迁移视频",
    model="W2.7r",
    video_url_list=["https://example.com/style1.mp4", "https://example.com/style2.mp4"],
    ratio="16:9",
    duration=10
)

# 视频 - Kling V3 Omni 多镜头模式
result = generate_video(
    prompt="电影预告片",
    model="KlingV3Omni",
    generation_type="TEXT",
    shot_type="multi",
    multi_shot=True,
    mode="pro"
)

# 视频 - Kling V3 Omni 参考主体
result = generate_video(
    prompt="角色在奔跑",
    model="KlingV3Omni",
    generation_type="REFERENCE",
    element_list=["https://example.com/character.jpg"],
    keep_original_sound=False
)

if result and result["status"] == "SUCCESS":
    print(f"媒体链接: {result['url']}")
    print(f"本地路径: {result.get('local_path')}")

图像生成前处理与参数变动

模型切换时的自动参数调整

当用户切换生成模型时，系统会自动调整以下参数：

模型与尺寸/质量的关系

图片生成时，size 参数会根据 methodType、quality 和用户选择的 ratio 自动计算：

生成前预处理参数

在调用生成 API 前，系统会自动添加以下限制参数：

图片生成限制参数说明

各模型的输入限制参数

根据选择的模型，系统会自动应用以下限制参数（targetMaxSize、targetMinLength、targetMaxLength）：

图片生成提示词长度限制

参数说明

图片上传合规性要求

通用要求：

• 支持格式：JPEG、JPG、PNG、WEBP（部分模型支持 BMP、TIFF、GIF）
• 文件大小：根据模型不同，限制为 10MB-30MB
• 最长边限制：根据模型不同，限制为 2000px-8000px

内容审查要求（Sora2/Veo 系列）：

1. 不得包含真人或拟真人图像
2. 提示词禁止暴力、色情、版权侵权或涉及名人信息

Wan 系列特殊要求：

1. 不支持透明通道（PNG 透明部分会被处理）
2. 宽高比必须在 [1:8, 8:1] 范围内

Seedance 系列特殊要求：

1. 宽高比（宽/高）必须在 (0.4, 2.5) 范围内
2. 上传图片最长边 ≤ 6000px，最短边 ≥ 300px

图片分辨率映射规则

质量等级与分辨率对照表

系统根据选择的 quality（图片质量）和 ratio（画面比例）自动计算输出图片的分辨率（宽 x 高）。

不同模型的分辨率格式

分辨率计算示例

from scripts.generate_image import get_image_resolution

# 获取 2K 质量、16:9 比例的分辨率
resolution = get_image_resolution(quality="2K", ratio="16:9")
print(resolution)  # 输出: [2560, 1440]

# 获取 4K 质量、1:1 比例的分辨率
resolution = get_image_resolution(quality="4K", ratio="1:1")
print(resolution)  # 输出: [4096, 4096]

# 仅获取质量对应的所有分辨率
resolutions = get_image_resolution(quality="2K")
print(resolutions)  # 输出: {'1:1': [2048, 2048], '16:9': [2560, 1440], ...}

视频生成前处理与参数变动

模型切换时的自动参数调整

当用户切换视频模型时，系统会自动调整以下参数：

镜头模式切换规则

当用户切换镜头模式时，系统会自动调整以下参数：

分辨率与比例的联动规则

生成类型切换时的参数重置

当用户切换生成类型时，系统会自动清空以下关联参数：

在调用生成 API 前，系统会自动进行以下处理：

参数校验规则

生成前系统会进行以下校验：

使用示例

from scripts.generate_video import generate_video

# 1. 模型切换示例 - 切换到 W2.6t 自动变为文生视频
result = generate_video(
    prompt="海边日落",
    model="W2.6t"
    # generation_type 会自动设置为 "TEXT"
)

# 2. 模型切换示例 - 切换到 Kling 自动变为多镜头模式
result = generate_video(
    prompt="电影预告片",
    model="KlingV3Omni"
    # shot_type 会自动设置为 "multi"
    # multi_shot 会自动设置为 True
)

# 3. 自定义多镜头模式
result = generate_video(
    prompt="",
    model="KlingV3Omni",
    shot_type="customize",
    multi_prompt=[
        {"index": 1, "prompt": "镜头1描述", "duration": 3},
        {"index": 2, "prompt": "镜头2描述", "duration": 3}
    ],
    duration=6
)

# 4. Kling 视频编辑模式（自动关闭音频生成）
result = generate_video(
    prompt="编辑这段视频",
    model="KlingV3Omni",
    generation_type="EDIT",
    first_clip_url="https://example.com/video.mp4",
    keep_original_sound=True
    # generate_audio 会自动设置为 False
)

# 5. Sora2 Pro - 分辨率与比例联动
result = generate_video(
    prompt="风景大片",
    model="Sora2Pro",
    resolution="2K",  # 2K 分辨率时比例会自动推荐 7:4
    ratio="7:4"
)

# 6. Wan R2V - 多参考素材
result = generate_video(
    prompt="风格迁移",
    model="W2.7r",
    image_url_list=["https://example.com/img1.jpg", "https://example.com/img2.jpg"],
    video_url_list=["https://example.com/style.mp4"]
    # 总数不能超过 5 个（图片+视频）
)

使用示例

from scripts.generate_image import generate_image

# 模型切换时的自动参数调整示例
# 1. 切换到 N1 模型时，quality 自动变为 "1K"
result = generate_image(
    prompt="一只猫",
    model="N1"  # quality 会自动设为 "1K"
)

# 2. 切换到 S5.0L 模型时，web_search 自动开启
result = generate_image(
    prompt="2024年流行的设计趋势",
    model="S5.0L"  # web_search 会自动设为 True
)

# 3. 手动覆盖自动参数（按此优先级：用户指定 > 系统默认）
result = generate_image(
    prompt="一只猫",
    model="N1",
    quality="2K"  # 手动指定会覆盖系统的 "1K" 默认值
)

视频模型输入限制参数

各视频模型的输入限制

根据选择的模型，系统会自动应用以下限制参数（图片、音频、视频上传）：

图片上传限制

音频上传限制

视频上传限制

负向提示词支持

Kling V3 Omni 特殊限制

当使用 Kling V3 Omni 模型时，参考图片数量限制根据是否有编辑视频动态变化：

参数说明

视频分辨率映射规则

质量等级与分辨率对照表

系统根据选择的 resolution（视频质量）和 ratio（画面比例）自动计算输出视频的分辨率（宽 x 高）。

不同视频模型的尺寸输出格式

分辨率计算示例

from scripts.generate_video import get_video_resolution

# 获取 1080p 质量、16:9 比例的分辨率
resolution = get_video_resolution(quality="1080p", ratio="16:9")
print(resolution)  # 输出: [1920, 1080]

# 获取 720p 质量、1:1 比例的分辨率
resolution = get_video_resolution(quality="720p", ratio="1:1")
print(resolution)  # 输出: [960, 960]

# 获取 2K 质量、7:4 比例的分辨率
resolution = get_video_resolution(quality="2K", ratio="7:4")
print(resolution)  # 输出: [1792, 1024]

# 仅获取质量对应的所有分辨率
resolutions = get_video_resolution(quality="1080p")
print(resolutions)  # 输出: {'1:1': [1440, 1440], '16:9': [1920, 1080], '9:16': [1080, 1920], '3:4': [1248, 1632], '4:3': [1632, 1248]}

视频提示词写作建议

推荐书写模版：主体 + 运动，背景 + 运动，镜头 + 运动 ...

1. 基础结构：图生视频已经有了场景，因此尽量减少（甚至避免）对静止/无变化部分的描述，在明确指出运动对象的情况下，多描述运动的部分，包括主体的运动、背景的运动/变化、以及镜头的运动。

2. 简单直接：尽量使用简单词语和句子结构，模型会根据我们的表达与对图像画面的理解进行提示词扩写，生成符合预期的视频。

3. 特征描述：当主体具有一些突出特征时，可以加上突出特征来更好定位主体，比如老人、戴墨镜的女人等。描述运动时，关键的程度副词一定要明确，比如快速、幅度大。

4. 遵从图片：需要基于输入的图片内容来写，需要明确写出主体以及想做的动作或者运镜，需注意提示词不要与图片内容/基础参数存在事实矛盾。

5. 负向提示词：部分模型不响应负向提示词（如 Kling V3 Omni），请查阅上方各模型说明。

返回字段

环境配置

必需配置 - API Key

重要：使用前必须设置你自己的 API Key！

获取 API Key

1. 访问 https://ai.deepsop.com/
2. 注册并登录账号
3. 在控制台创建你的 API Key
4. 复制生成的 API Key（格式：sk-xxxxxx...）

方式 1：使用 .env 文件（推荐）

1. 复制 .env.example 为 .env：

   cp .env.example .env
   

2. 编辑 .env 文件，填入你的 API Key：

   AI_ARTIST_TOKEN=sk-your_api_key_here
   

3. 在运行脚本前加载环境变量：

   # Linux/macOS/Git Bash
   source .env
   
   # 或使用 export
   export $(cat .env | xargs)
   

方式 2：直接设置环境变量

Linux / macOS / Git Bash (Windows)

export AI_ARTIST_TOKEN="sk-your_api_key_here"

为了永久生效，将上述命令添加到 ~/.bashrc 或 ~/.zshrc 文件中。

Windows PowerShell

$env:AI_ARTIST_TOKEN="sk-your_api_key_here"

永久设置（系统级）：

[System.Environment]::SetEnvironmentVariable('AI_ARTIST_TOKEN', 'sk-your_api_key_here', 'User')

Windows CMD

set AI_ARTIST_TOKEN=sk-your_api_key_here

验证配置

运行以下命令验证 API Key 是否设置成功：

# Linux/macOS/Git Bash
echo $AI_ARTIST_TOKEN

# Windows PowerShell
echo $env:AI_ARTIST_TOKEN

# Windows CMD
echo %AI_ARTIST_TOKEN%

如果输出为空或显示默认值，说明环境变量未正确设置。

测试配置（推荐）

运行配置测试脚本，验证 API Key 是否正确设置：

python3 scripts/test_config.py

该脚本会检查：

• API Key 是否已设置
• 是否使用了默认 Key（需要替换为你自己的）
• 配置是否可以正常使用

可选配置 - 飞书通知

export FEISHU_WEBHOOK_URL="https://open.feishu.cn/open-apis/bot/v2/hook/xxx"

相关文件

• scripts/generate_image.py - 图片生成脚本
• scripts/generate_video.py - 视频生成脚本
• references/api.md - API 详细文档