Anil-matcha/Seedance-2-API

概览

Seedance‑2‑API 是一个围绕字节跳动 Seedance 视频生成模型（2.0、2.5 和较新的 2 Mini）的 Python 封装库。该封装库与公开的 MuAPI 端点进行通信，处理身份验证、请求格式化以及结果轮询。它让开发者能够从文本提示生成电影级 AI 视频、为静态图片制作动画、编辑现有剪辑，并在多次生成中保持角色一致性。

---

库功能

功能	描述
文本转视频 (T2V)	发送自然语言提示并接收高质量视频（1080p，2.5 版本支持 4K）。
图片转视频 (I2V)	提供一张或多张参考图片；模型会根据提示将其动画化。
全能参考 (Omni‑Reference)	在单个请求中结合图片、视频和音频参考，以获得更丰富的条件设置。
角色表 (Character Sheets)	从 1‑3 张照片生成多视角角色参考；在后续提示中使用 @character:<id> 重复使用以保持脸部一致。
视频编辑 (Video‑Edit)	使用文本描述和可选的参考媒体修改现有视频。
Mini 模型	低成本、快速的变体 (Seedance 2 Mini)，具有独立的 SDK 调用 (text_to_video_mini, image_to_video_mini)。
MCP 服务器	可选的 Model Context Protocol 服务器，让其他 AI 助手（如 Claude、Cursor 等）可以直接调用 Seedance。
实用工具	文件上传、基于环境变量的 API 密钥处理，以及一个 wait_for_completion 辅助函数，用于轮询 MuAPI 状态端点。

---

如何开始

# 从 PyPI 安装（推荐）
pip install seedance-2-api

创建一个 .env 文件并填入您的 MuAPI 密钥：

MUAPI_API_KEY=your_muapi_api_key_here

基本使用示例（文本转视频）：

from seedance_api import SeedanceAPI
api = SeedanceAPI()
submission = api.text_to_video(
    prompt="A cinematic slow‑motion shot of a cyberpunk city in the rain, neon lights reflecting on puddles",
    aspect_ratio="16:9",
    duration=5,
    quality="high",
)
result = api.wait_for_completion(submission["request_id"])
print("Video URL:", result["url"])

相同的模式也适用于 Mini 模型 (text_to_video_mini) 或图片转视频 (image_to_video, image_to_video_mini)。

---

核心概念

• 请求 ID (Request IDs) – 每个 MuAPI 调用都会返回一个 request_id。使用 api.wait_for_completion(request_id) 进行轮询，直到视频准备就绪。
• 角色工作流程 – 首先使用参考照片调用 api.create_character (或 api.character)，等待角色表生成，然后在后续提示中通过 @character:<request_id> 引用它。
• MCP 服务器 – 运行 python3 mcp_server.py 以通过 Model Context Protocol 公开此封装库，使其他 AI 工具无需编写 HTTP 代码即可调用 Seedance。

---

何时使用此库

• 您需要高保真 AI 视频 (1080p‑4K) 而无需构建自己的推理堆栈。
• 您的应用程序受益于在多个剪辑中保持角色一致性。
• 您偏好简单的 Python 接口而非原始的 curl 调用。
• 您想要尝试低成本的 Mini 模型以进行快速原型设计或大规模管线作业。

---

限制与注意事项

• 本库仅为轻量级客户端；所有繁重的工作（模型推理、渲染）均在 MuAPI 的服务器上进行。
• 每个请求都会产生费用（例如，角色表为 $0.18，Mini 模型约为 $0.073/秒）。请通过您的 MuAPI 账户监控使用量。
• 内容政策比某些竞争对手更宽松，但您仍需遵守 MuAPI 的服务条款。

---

相关项目 (来自 README)

• Seedance‑2‑Spicy‑API, Seedance‑2.5‑Spicy‑API – 针对“放宽审核”层级的封装库。
• MiniMax‑H3‑API, Wan‑3.0‑API – 其他字节跳动视频模型的封装库。
• seedance‑2‑mcp, seedance‑2.5‑mcp – 专注于 MCP 的服务器。
• awesome‑seedance‑*‑prompts – 精选提示词集合。

---

总结

seedance-2-api 是一个真正可投入生产的 Python SDK，用于字节跳动的 Seedance 视频生成模型，通过 MuAPI 提供文本转视频、图片转视频、角色一致性、视频编辑以及低成本的 Mini 变体。使用 pip 安装，设置您的 MuAPI 密钥，并调用高级方法，只需几行代码即可生成电影级的 AI 视频。