crewai-seedance 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- crewai_seedance-0.1.0/.env.example +1 -0
- crewai_seedance-0.1.0/.github/workflows/test.yml +24 -0
- crewai_seedance-0.1.0/.gitignore +9 -0
- crewai_seedance-0.1.0/LICENSE +21 -0
- crewai_seedance-0.1.0/PKG-INFO +140 -0
- crewai_seedance-0.1.0/PRIVACY.md +7 -0
- crewai_seedance-0.1.0/README.md +123 -0
- crewai_seedance-0.1.0/README.pypi.md +123 -0
- crewai_seedance-0.1.0/assets/tutorial/create-api-key-en.png +0 -0
- crewai_seedance-0.1.0/assets/tutorial/get-api-key-en.png +0 -0
- crewai_seedance-0.1.0/assets/tutorial/official-crewai-tracing.png +0 -0
- crewai_seedance-0.1.0/assets/tutorial/source.json +8 -0
- crewai_seedance-0.1.0/examples/query_existing.py +10 -0
- crewai_seedance-0.1.0/pyproject.toml +28 -0
- crewai_seedance-0.1.0/readme/README_zh_Hans.md +118 -0
- crewai_seedance-0.1.0/src/seedance_crewai/__init__.py +5 -0
- crewai_seedance-0.1.0/src/seedance_crewai/_base.py +233 -0
- crewai_seedance-0.1.0/src/seedance_crewai/tools.py +107 -0
- crewai_seedance-0.1.0/tests/contract-source.json +293 -0
- crewai_seedance-0.1.0/tests/live-readonly-evidence.json +16 -0
- crewai_seedance-0.1.0/tests/service.json +28 -0
- crewai_seedance-0.1.0/tests/test_agent.py +138 -0
- crewai_seedance-0.1.0/tests/test_tools.py +273 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
ACEDATACLOUD_API_KEY=your_api_consumer_token
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
name: Test and build
|
|
2
|
+
on:
|
|
3
|
+
push:
|
|
4
|
+
pull_request:
|
|
5
|
+
jobs:
|
|
6
|
+
test:
|
|
7
|
+
runs-on: ubuntu-latest
|
|
8
|
+
strategy:
|
|
9
|
+
matrix:
|
|
10
|
+
python: ['3.10', '3.12', '3.13']
|
|
11
|
+
steps:
|
|
12
|
+
- uses: actions/checkout@v4
|
|
13
|
+
- uses: astral-sh/setup-uv@v6
|
|
14
|
+
with:
|
|
15
|
+
python-version: ${{ matrix.python }}
|
|
16
|
+
- run: uv sync --group dev
|
|
17
|
+
- run: uv run pytest
|
|
18
|
+
- run: uv run ruff check .
|
|
19
|
+
- run: uv build
|
|
20
|
+
- name: Install built wheel in a clean environment
|
|
21
|
+
run: |
|
|
22
|
+
uv venv /tmp/service-wheel --python ${{ matrix.python }}
|
|
23
|
+
uv pip install --python /tmp/service-wheel/bin/python dist/crewai_seedance-0.1.0-py3-none-any.whl
|
|
24
|
+
/tmp/service-wheel/bin/python -c 'from seedance_crewai import SeedanceGenerateVideoTool, SeedanceRetrieveTaskTool; t = SeedanceRetrieveTaskTool(api_key="fixture"); assert "fixture" not in str(t.model_dump()); assert "task_id" in t.args_schema.model_fields; print("clean wheel import and schema passed")'
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ace Data Cloud
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: crewai-seedance
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Seedance by Ace Data Cloud: native CrewAI video generation and same-task retrieval tools
|
|
5
|
+
Project-URL: Homepage, https://github.com/AceDataCloud/SeedanceCrewAI
|
|
6
|
+
Project-URL: Repository, https://github.com/AceDataCloud/SeedanceCrewAI
|
|
7
|
+
Project-URL: Issues, https://github.com/AceDataCloud/SeedanceCrewAI/issues
|
|
8
|
+
Author-email: Ace Data Cloud Dev <dev@acedata.cloud>
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: acedatacloud,agents,crewai,seedance,video
|
|
12
|
+
Requires-Python: <3.14,>=3.10
|
|
13
|
+
Requires-Dist: crewai<2,>=1.15.28
|
|
14
|
+
Requires-Dist: httpx<1,>=0.28
|
|
15
|
+
Requires-Dist: pydantic<3,>=2.11
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
|
|
18
|
+
# Seedance by Ace Data Cloud for CrewAI
|
|
19
|
+
|
|
20
|
+
Independent native **Seedance** video tools for CrewAI. Provided by **Ace Data Cloud**, not an official Seedance or CrewAI product. This is a standalone service package; no all-services bundle or generic provider setup is required.
|
|
21
|
+
|
|
22
|
+
[简体中文](https://github.com/AceDataCloud/SeedanceCrewAI/blob/322302879cf59f0e16e5f743fb5a1c76f90636dd/readme/README_zh_Hans.md) · [Current models and prices](https://platform.acedata.cloud/models?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=seedancecrewai_package_pricing)
|
|
23
|
+
|
|
24
|
+
## 1. Install the correct service package
|
|
25
|
+
|
|
26
|
+
Review-preview source and a [GitHub wheel/sdist prerelease](https://github.com/AceDataCloud/SeedanceCrewAI/releases/tag/v0.1.0-preview.2) are available; implementation remains under review. **Not yet PyPI-published or listed in the official CrewAI / AMP catalog.** The source version below is pinned to `ca0135e30f90b38fd243cb4ea9e3ba7b93926afe`. Do not treat a repository as an official listing.
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
uv add 'crewai-seedance @ git+https://github.com/AceDataCloud/SeedanceCrewAI.git@ca0135e30f90b38fd243cb4ea9e3ba7b93926afe'
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The pinned SHA is the version published in the review preview; inspect [source PR #1](https://github.com/AceDataCloud/SeedanceCrewAI/pull/1) before adoption. After verified PyPI publication the standard command will be `uv add crewai-seedance`; do not assume it works before publication. CrewAI supports Python 3.10–3.13. Intel macOS may lack its mandatory lancedb wheel; use supported Linux rather than bypassing dependencies for production.
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
uv add 'crewai-seedance @ https://github.com/AceDataCloud/SeedanceCrewAI/releases/download/v0.1.0-preview.2/crewai_seedance-0.1.0-py3-none-any.whl#sha256=29d07b8fcab285ccb85daa5890139df05bb4c29331e0dfb7416d33bd6471ba58'
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The fixed preview.2 wheel was built from the same terminal-state-verified source `ca0135e30f90b38fd243cb4ea9e3ba7b93926afe` used by the pinned source install. Historical preview.1 is retained unchanged. SHA256 must match; the mutable release page/tag is informational, not a trust anchor.
|
|
40
|
+
|
|
41
|
+
## 2. Register / sign in and get your own API Token
|
|
42
|
+
|
|
43
|
+
1. Open [Ace Data Cloud → Applications](https://platform.acedata.cloud/console/applications?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=seedancecrewai_package_api_key); register and sign in. If needed, choose **Initialize General Application**.
|
|
44
|
+
2. Open **General application**, check **Seedance** service access, current model price and balance. A service-specific application can only use its entitled service.
|
|
45
|
+
3. Copy the selected API Key using icon **1**, or **Manage Keys** **2** → **Create** for a separate `Seedance CrewAI` key.
|
|
46
|
+
|
|
47
|
+

|
|
48
|
+
|
|
49
|
+
4. Configure expiration and usage limits only as needed. If **Allowed APIs** is enabled, include both `/seedance/videos` and `/seedance/tasks`.
|
|
50
|
+
|
|
51
|
+

|
|
52
|
+
|
|
53
|
+
Historical authentic Ace screenshots reused unchanged from SunoDify commit `8d3d03570e73324220f111f7fe343da0792a8071`, retrieved 2026-10-18. The second image's old name `Dify tutorial` is an example only: use `Seedance CrewAI`. No visible real credential is included; [image sources](https://raw.githubusercontent.com/AceDataCloud/SeedanceCrewAI/ca0135e30f90b38fd243cb4ea9e3ba7b93926afe/assets/tutorial/source.json).
|
|
54
|
+
|
|
55
|
+
Set the raw consumer Token in environment variable `ACEDATACLOUD_API_KEY` through secure terminal input or a secret manager. It is not a `platform-...` management Token and must not include `Bearer `, spaces or quotation marks. Never place it in prompts, screenshots, committed `.env` or workflow exports. `api_key=...` may be supplied from secure credential storage and is excluded from serialization.
|
|
56
|
+
|
|
57
|
+
## 3. Add the named native tools
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from crewai import Agent
|
|
61
|
+
from seedance_crewai import SeedanceGenerateVideoTool, SeedanceRetrieveTaskTool
|
|
62
|
+
|
|
63
|
+
agent = Agent(
|
|
64
|
+
role="Seedance producer",
|
|
65
|
+
goal="Create the approved media, then retrieve the original task result",
|
|
66
|
+
backstory="Use Seedance through Ace Data Cloud within the user's approved budget.",
|
|
67
|
+
llm=your_configured_llm,
|
|
68
|
+
tools=[SeedanceGenerateVideoTool(), SeedanceRetrieveTaskTool()],
|
|
69
|
+
allow_delegation=False,
|
|
70
|
+
max_retry_limit=0,
|
|
71
|
+
)
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The two discoverable tool names are **Seedance by Ace Data Cloud - Generate Video** and **Seedance by Ace Data Cloud - Retrieve Task**. The Token goes in the environment, not a custom MCP header or agent prompt. Adding tools does not execute them. The caller approves paid requests; generation defaults to one use per instance to reduce duplicate submissions, which is not a funds cap or a permission system.
|
|
75
|
+
|
|
76
|
+
## 4. Service-specific input and first use
|
|
77
|
+
|
|
78
|
+
Structured `content`: text, image URL (+ first/last/reference role), audio URL (+ reference_audio), video URL (+ reference_video). Lowercase `resolution` (`480p/720p/1080p/4k`), `ratio`, optional duration -1..30, frames, seed, camerafixed, watermark, generate_audio and return_last_frame. Availability and valid combinations depend on the selected public model. This package does not expose web search, callbacks, expiry, priority or provider admin fields.
|
|
79
|
+
|
|
80
|
+
Check [the current model catalog and price](https://platform.acedata.cloud/models?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=seedancecrewai_package_first_use) before calling; model IDs are passed unchanged and no substitute model is added. The following values are examples from the pinned current API contract, not permanent defaults. **Executing generation is billable**; this guide does not run it.
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
import json
|
|
84
|
+
from seedance_crewai import SeedanceGenerateVideoTool, SeedanceRetrieveTaskTool
|
|
85
|
+
|
|
86
|
+
parameters = {
|
|
87
|
+
"model": "doubao-seedance-2-0-mini-260615",
|
|
88
|
+
"content": [
|
|
89
|
+
{
|
|
90
|
+
"type": "text",
|
|
91
|
+
"text": "A calm sunrise over a mountain lake"
|
|
92
|
+
}
|
|
93
|
+
],
|
|
94
|
+
"resolution": "480p",
|
|
95
|
+
"ratio": "16:9",
|
|
96
|
+
"generate_audio": False
|
|
97
|
+
}
|
|
98
|
+
# BILLABLE when executed; approve the current model and budget first.
|
|
99
|
+
submitted = SeedanceGenerateVideoTool().run(**parameters)
|
|
100
|
+
submitted = json.loads(submitted) # A ToolFailure must be handled before this step.
|
|
101
|
+
task_id = submitted["task_id"]
|
|
102
|
+
result = SeedanceRetrieveTaskTool().run(task_id=task_id, wait_seconds=240)
|
|
103
|
+
print(result)
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The request submits once with `async=true`. accepted/pending is **not** a terminal result, even when an envelope has success=true. Preserve the original task ID; pending, timeouts or unknown submission outcomes do not authorize another generation. Bounded wait only queries that same ID, and can include an in-flight request timeout. Continue using Retrieve Task until terminal status. A true completed response requires the stored finished_at, service success and a valid target media URL. Nested failed states are treated as failure; a missing terminal media link is not fake success.
|
|
107
|
+
|
|
108
|
+
For a task you already own, run only this read-only example:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
uv run python examples/query_existing.py YOUR_EXISTING_TASK_ID
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
The query is `POST /seedance/tasks` with `action=retrieve,id=...`. A completed result returns `status=succeeded`, `success=true`, `task_id`, filtered `media_urls` and original `cost` in Credits when present. No raw original prompt, request, account/application identity, internal diagnostics or unfiltered body is returned. `cost` is not a new bill or USD amount. URL presence does not verify ongoing media playback.
|
|
115
|
+
|
|
116
|
+
## 5. Inspect execution and output
|
|
117
|
+
|
|
118
|
+

|
|
119
|
+
|
|
120
|
+
Official [CrewAI tracing reference](https://docs.crewai.com/en/observability/tracing), historical date marker 10/1/2025, capture version unspecified; retrieved 2026-10-18. Left: task and tool timeline; right: expanded Response output, not input. **Not this package running, not an Ace task and not a promised new GUI.** Trace account/auth/consent is optional and not enabled by this package. For your actual run inspect the named tool and its returned terminal fields; never expose Token or private media URLs in screenshots.
|
|
121
|
+
|
|
122
|
+
## Troubleshooting, privacy and cost
|
|
123
|
+
|
|
124
|
+
| Result | Action |
|
|
125
|
+
|---|---|
|
|
126
|
+
| 401 / 403 | Check full raw consumer Token, expiration, service entitlement, Allowed APIs and balance. A 403 is not always moderation. |
|
|
127
|
+
| 400 / schema rejection | Follow this service's fields, casing and model capability; unknown cross-service fields are rejected before network. |
|
|
128
|
+
| pending / no media yet | Query the same original task ID; never regenerate to poll. |
|
|
129
|
+
| 429 | Reduce concurrency and wait. One HTTP attempt per operation; your configured LLM/agent may retry separately. |
|
|
130
|
+
| Timeout / 5xx | Submission outcome can be unknown. Inspect request history before creating another task. |
|
|
131
|
+
| ToolFailure | Failed task or invalid terminal media; structured non-retryable result. Preserve task/trace ID for support, never Key. |
|
|
132
|
+
| Result URL cannot open | Check terminal success and your network; link existence alone is not playback evidence. |
|
|
133
|
+
|
|
134
|
+
The code is free; media generation and the LLM you configure have their current prices. No payment handler, fallback or automatic paid HTTP retry is added. Original Credits cost follows the API's current package/account rate and discounts; this package does not hard-code USD conversion. No install/CI count is presented as users or revenue.
|
|
135
|
+
|
|
136
|
+
Provided prompts/references and the consumer Token are sent to `api.acedata.cloud` over HTTPS. The package adds no telemetry or tracing; CrewAI/your LLM may have separate settings. [Privacy](https://github.com/AceDataCloud/SeedanceCrewAI/blob/322302879cf59f0e16e5f743fb5a1c76f90636dd/PRIVACY.md). [Source](https://github.com/AceDataCloud/SeedanceCrewAI) · [Issues](https://github.com/AceDataCloud/SeedanceCrewAI/issues) · dev@acedata.cloud
|
|
137
|
+
|
|
138
|
+
Development: `uv sync --group dev`, `uv run pytest`, `uv run ruff check .`, `uv build`. Paid HTTP is mocked in tests; native Agent/Task/Crew cycles use a deterministic local model fixture. See `tests/contract-source.json` for immutable service contract provenance and `tests/live-readonly-evidence.json` when an old-task check is available. No new paid request runs in CI.
|
|
139
|
+
|
|
140
|
+
The pinned source and preview.2 include explicit failed-state handling before finished_at. Historical preview.1 remains unchanged; use the pinned fixed version above.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Privacy
|
|
2
|
+
|
|
3
|
+
The tools send user-selected media prompts/references and the API-consumer Token to `api.acedata.cloud` over HTTPS. The Token is read from an environment variable or explicit secure input and excluded from tool serialization. The package adds no analytics or telemetry and does not enable CrewAI tracing. CrewAI, the configured LLM, and the caller may have separate telemetry or trace settings. Do not place secrets or personal data in media prompts/references without authorization.
|
|
4
|
+
|
|
5
|
+
Returned fields are limited to task status, the task ID, HTTPS video result URLs and original cost. Raw request payloads and account/application identities are excluded. Optional task polling queries only the same ID. The caller controls retention, LLM context sharing and logging. Do not publish private media links or keys in bug reports.
|
|
6
|
+
|
|
7
|
+
The API and any configured LLM follow current prices and data handling terms; this package does not accept terms or create an account for the user.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Seedance by Ace Data Cloud for CrewAI
|
|
2
|
+
|
|
3
|
+
Independent native **Seedance** video tools for CrewAI. Provided by **Ace Data Cloud**, not an official Seedance or CrewAI product. This is a standalone service package; no all-services bundle or generic provider setup is required.
|
|
4
|
+
|
|
5
|
+
[简体中文](readme/README_zh_Hans.md) · [Current models and prices](https://platform.acedata.cloud/models?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=seedancecrewai_readme_pricing)
|
|
6
|
+
|
|
7
|
+
## 1. Install the correct service package
|
|
8
|
+
|
|
9
|
+
Review-preview source and a [GitHub wheel/sdist prerelease](https://github.com/AceDataCloud/SeedanceCrewAI/releases/tag/v0.1.0-preview.2) are available; implementation remains under review. **Not yet PyPI-published or listed in the official CrewAI / AMP catalog.** The source version below is pinned to `ca0135e30f90b38fd243cb4ea9e3ba7b93926afe`. Do not treat a repository as an official listing.
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
uv add 'crewai-seedance @ git+https://github.com/AceDataCloud/SeedanceCrewAI.git@ca0135e30f90b38fd243cb4ea9e3ba7b93926afe'
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
The pinned SHA is the version published in the review preview; inspect [source PR #1](https://github.com/AceDataCloud/SeedanceCrewAI/pull/1) before adoption. After verified PyPI publication the standard command will be `uv add crewai-seedance`; do not assume it works before publication. CrewAI supports Python 3.10–3.13. Intel macOS may lack its mandatory lancedb wheel; use supported Linux rather than bypassing dependencies for production.
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
uv add 'crewai-seedance @ https://github.com/AceDataCloud/SeedanceCrewAI/releases/download/v0.1.0-preview.2/crewai_seedance-0.1.0-py3-none-any.whl#sha256=29d07b8fcab285ccb85daa5890139df05bb4c29331e0dfb7416d33bd6471ba58'
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The fixed preview.2 wheel was built from the same terminal-state-verified source `ca0135e30f90b38fd243cb4ea9e3ba7b93926afe` used by the pinned source install. Historical preview.1 is retained unchanged. SHA256 must match; the mutable release page/tag is informational, not a trust anchor.
|
|
23
|
+
|
|
24
|
+
## 2. Register / sign in and get your own API Token
|
|
25
|
+
|
|
26
|
+
1. Open [Ace Data Cloud → Applications](https://platform.acedata.cloud/console/applications?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=seedancecrewai_readme_api_key); register and sign in. If needed, choose **Initialize General Application**.
|
|
27
|
+
2. Open **General application**, check **Seedance** service access, current model price and balance. A service-specific application can only use its entitled service.
|
|
28
|
+
3. Copy the selected API Key using icon **1**, or **Manage Keys** **2** → **Create** for a separate `Seedance CrewAI` key.
|
|
29
|
+
|
|
30
|
+

|
|
31
|
+
|
|
32
|
+
4. Configure expiration and usage limits only as needed. If **Allowed APIs** is enabled, include both `/seedance/videos` and `/seedance/tasks`.
|
|
33
|
+
|
|
34
|
+

|
|
35
|
+
|
|
36
|
+
Historical authentic Ace screenshots reused unchanged from SunoDify commit `8d3d03570e73324220f111f7fe343da0792a8071`, retrieved 2026-10-18. The second image's old name `Dify tutorial` is an example only: use `Seedance CrewAI`. No visible real credential is included; [image sources](assets/tutorial/source.json).
|
|
37
|
+
|
|
38
|
+
Set the raw consumer Token in environment variable `ACEDATACLOUD_API_KEY` through secure terminal input or a secret manager. It is not a `platform-...` management Token and must not include `Bearer `, spaces or quotation marks. Never place it in prompts, screenshots, committed `.env` or workflow exports. `api_key=...` may be supplied from secure credential storage and is excluded from serialization.
|
|
39
|
+
|
|
40
|
+
## 3. Add the named native tools
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
from crewai import Agent
|
|
44
|
+
from seedance_crewai import SeedanceGenerateVideoTool, SeedanceRetrieveTaskTool
|
|
45
|
+
|
|
46
|
+
agent = Agent(
|
|
47
|
+
role="Seedance producer",
|
|
48
|
+
goal="Create the approved media, then retrieve the original task result",
|
|
49
|
+
backstory="Use Seedance through Ace Data Cloud within the user's approved budget.",
|
|
50
|
+
llm=your_configured_llm,
|
|
51
|
+
tools=[SeedanceGenerateVideoTool(), SeedanceRetrieveTaskTool()],
|
|
52
|
+
allow_delegation=False,
|
|
53
|
+
max_retry_limit=0,
|
|
54
|
+
)
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The two discoverable tool names are **Seedance by Ace Data Cloud - Generate Video** and **Seedance by Ace Data Cloud - Retrieve Task**. The Token goes in the environment, not a custom MCP header or agent prompt. Adding tools does not execute them. The caller approves paid requests; generation defaults to one use per instance to reduce duplicate submissions, which is not a funds cap or a permission system.
|
|
58
|
+
|
|
59
|
+
## 4. Service-specific input and first use
|
|
60
|
+
|
|
61
|
+
Structured `content`: text, image URL (+ first/last/reference role), audio URL (+ reference_audio), video URL (+ reference_video). Lowercase `resolution` (`480p/720p/1080p/4k`), `ratio`, optional duration -1..30, frames, seed, camerafixed, watermark, generate_audio and return_last_frame. Availability and valid combinations depend on the selected public model. This package does not expose web search, callbacks, expiry, priority or provider admin fields.
|
|
62
|
+
|
|
63
|
+
Check [the current model catalog and price](https://platform.acedata.cloud/models?utm_source=github&utm_medium=referral&utm_campaign=evergreen&utm_content=seedancecrewai_readme_first_use) before calling; model IDs are passed unchanged and no substitute model is added. The following values are examples from the pinned current API contract, not permanent defaults. **Executing generation is billable**; this guide does not run it.
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
import json
|
|
67
|
+
from seedance_crewai import SeedanceGenerateVideoTool, SeedanceRetrieveTaskTool
|
|
68
|
+
|
|
69
|
+
parameters = {
|
|
70
|
+
"model": "doubao-seedance-2-0-mini-260615",
|
|
71
|
+
"content": [
|
|
72
|
+
{
|
|
73
|
+
"type": "text",
|
|
74
|
+
"text": "A calm sunrise over a mountain lake"
|
|
75
|
+
}
|
|
76
|
+
],
|
|
77
|
+
"resolution": "480p",
|
|
78
|
+
"ratio": "16:9",
|
|
79
|
+
"generate_audio": False
|
|
80
|
+
}
|
|
81
|
+
# BILLABLE when executed; approve the current model and budget first.
|
|
82
|
+
submitted = SeedanceGenerateVideoTool().run(**parameters)
|
|
83
|
+
submitted = json.loads(submitted) # A ToolFailure must be handled before this step.
|
|
84
|
+
task_id = submitted["task_id"]
|
|
85
|
+
result = SeedanceRetrieveTaskTool().run(task_id=task_id, wait_seconds=240)
|
|
86
|
+
print(result)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The request submits once with `async=true`. accepted/pending is **not** a terminal result, even when an envelope has success=true. Preserve the original task ID; pending, timeouts or unknown submission outcomes do not authorize another generation. Bounded wait only queries that same ID, and can include an in-flight request timeout. Continue using Retrieve Task until terminal status. A true completed response requires the stored finished_at, service success and a valid target media URL. Nested failed states are treated as failure; a missing terminal media link is not fake success.
|
|
90
|
+
|
|
91
|
+
For a task you already own, run only this read-only example:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
uv run python examples/query_existing.py YOUR_EXISTING_TASK_ID
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
The query is `POST /seedance/tasks` with `action=retrieve,id=...`. A completed result returns `status=succeeded`, `success=true`, `task_id`, filtered `media_urls` and original `cost` in Credits when present. No raw original prompt, request, account/application identity, internal diagnostics or unfiltered body is returned. `cost` is not a new bill or USD amount. URL presence does not verify ongoing media playback.
|
|
98
|
+
|
|
99
|
+
## 5. Inspect execution and output
|
|
100
|
+
|
|
101
|
+

|
|
102
|
+
|
|
103
|
+
Official [CrewAI tracing reference](https://docs.crewai.com/en/observability/tracing), historical date marker 10/1/2025, capture version unspecified; retrieved 2026-10-18. Left: task and tool timeline; right: expanded Response output, not input. **Not this package running, not an Ace task and not a promised new GUI.** Trace account/auth/consent is optional and not enabled by this package. For your actual run inspect the named tool and its returned terminal fields; never expose Token or private media URLs in screenshots.
|
|
104
|
+
|
|
105
|
+
## Troubleshooting, privacy and cost
|
|
106
|
+
|
|
107
|
+
| Result | Action |
|
|
108
|
+
|---|---|
|
|
109
|
+
| 401 / 403 | Check full raw consumer Token, expiration, service entitlement, Allowed APIs and balance. A 403 is not always moderation. |
|
|
110
|
+
| 400 / schema rejection | Follow this service's fields, casing and model capability; unknown cross-service fields are rejected before network. |
|
|
111
|
+
| pending / no media yet | Query the same original task ID; never regenerate to poll. |
|
|
112
|
+
| 429 | Reduce concurrency and wait. One HTTP attempt per operation; your configured LLM/agent may retry separately. |
|
|
113
|
+
| Timeout / 5xx | Submission outcome can be unknown. Inspect request history before creating another task. |
|
|
114
|
+
| ToolFailure | Failed task or invalid terminal media; structured non-retryable result. Preserve task/trace ID for support, never Key. |
|
|
115
|
+
| Result URL cannot open | Check terminal success and your network; link existence alone is not playback evidence. |
|
|
116
|
+
|
|
117
|
+
The code is free; media generation and the LLM you configure have their current prices. No payment handler, fallback or automatic paid HTTP retry is added. Original Credits cost follows the API's current package/account rate and discounts; this package does not hard-code USD conversion. No install/CI count is presented as users or revenue.
|
|
118
|
+
|
|
119
|
+
Provided prompts/references and the consumer Token are sent to `api.acedata.cloud` over HTTPS. The package adds no telemetry or tracing; CrewAI/your LLM may have separate settings. [Privacy](PRIVACY.md). [Source](https://github.com/AceDataCloud/SeedanceCrewAI) · [Issues](https://github.com/AceDataCloud/SeedanceCrewAI/issues) · dev@acedata.cloud
|
|
120
|
+
|
|
121
|
+
Development: `uv sync --group dev`, `uv run pytest`, `uv run ruff check .`, `uv build`. Paid HTTP is mocked in tests; native Agent/Task/Crew cycles use a deterministic local model fixture. See `tests/contract-source.json` for immutable service contract provenance and `tests/live-readonly-evidence.json` when an old-task check is available. No new paid request runs in CI.
|
|
122
|
+
|
|
123
|
+
The pinned source and preview.2 include explicit failed-state handling before finished_at. Historical preview.1 remains unchanged; use the pinned fixed version above.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Seedance by Ace Data Cloud for CrewAI
|
|
2
|
+
|
|
3
|
+
Independent native **Seedance** video tools for CrewAI. Provided by **Ace Data Cloud**, not an official Seedance or CrewAI product. This is a standalone service package; no all-services bundle or generic provider setup is required.
|
|
4
|
+
|
|
5
|
+
[简体中文](https://github.com/AceDataCloud/SeedanceCrewAI/blob/322302879cf59f0e16e5f743fb5a1c76f90636dd/readme/README_zh_Hans.md) · [Current models and prices](https://platform.acedata.cloud/models?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=seedancecrewai_package_pricing)
|
|
6
|
+
|
|
7
|
+
## 1. Install the correct service package
|
|
8
|
+
|
|
9
|
+
Review-preview source and a [GitHub wheel/sdist prerelease](https://github.com/AceDataCloud/SeedanceCrewAI/releases/tag/v0.1.0-preview.2) are available; implementation remains under review. **Not yet PyPI-published or listed in the official CrewAI / AMP catalog.** The source version below is pinned to `ca0135e30f90b38fd243cb4ea9e3ba7b93926afe`. Do not treat a repository as an official listing.
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
uv add 'crewai-seedance @ git+https://github.com/AceDataCloud/SeedanceCrewAI.git@ca0135e30f90b38fd243cb4ea9e3ba7b93926afe'
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
The pinned SHA is the version published in the review preview; inspect [source PR #1](https://github.com/AceDataCloud/SeedanceCrewAI/pull/1) before adoption. After verified PyPI publication the standard command will be `uv add crewai-seedance`; do not assume it works before publication. CrewAI supports Python 3.10–3.13. Intel macOS may lack its mandatory lancedb wheel; use supported Linux rather than bypassing dependencies for production.
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
uv add 'crewai-seedance @ https://github.com/AceDataCloud/SeedanceCrewAI/releases/download/v0.1.0-preview.2/crewai_seedance-0.1.0-py3-none-any.whl#sha256=29d07b8fcab285ccb85daa5890139df05bb4c29331e0dfb7416d33bd6471ba58'
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The fixed preview.2 wheel was built from the same terminal-state-verified source `ca0135e30f90b38fd243cb4ea9e3ba7b93926afe` used by the pinned source install. Historical preview.1 is retained unchanged. SHA256 must match; the mutable release page/tag is informational, not a trust anchor.
|
|
23
|
+
|
|
24
|
+
## 2. Register / sign in and get your own API Token
|
|
25
|
+
|
|
26
|
+
1. Open [Ace Data Cloud → Applications](https://platform.acedata.cloud/console/applications?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=seedancecrewai_package_api_key); register and sign in. If needed, choose **Initialize General Application**.
|
|
27
|
+
2. Open **General application**, check **Seedance** service access, current model price and balance. A service-specific application can only use its entitled service.
|
|
28
|
+
3. Copy the selected API Key using icon **1**, or **Manage Keys** **2** → **Create** for a separate `Seedance CrewAI` key.
|
|
29
|
+
|
|
30
|
+

|
|
31
|
+
|
|
32
|
+
4. Configure expiration and usage limits only as needed. If **Allowed APIs** is enabled, include both `/seedance/videos` and `/seedance/tasks`.
|
|
33
|
+
|
|
34
|
+

|
|
35
|
+
|
|
36
|
+
Historical authentic Ace screenshots reused unchanged from SunoDify commit `8d3d03570e73324220f111f7fe343da0792a8071`, retrieved 2026-10-18. The second image's old name `Dify tutorial` is an example only: use `Seedance CrewAI`. No visible real credential is included; [image sources](https://raw.githubusercontent.com/AceDataCloud/SeedanceCrewAI/ca0135e30f90b38fd243cb4ea9e3ba7b93926afe/assets/tutorial/source.json).
|
|
37
|
+
|
|
38
|
+
Set the raw consumer Token in environment variable `ACEDATACLOUD_API_KEY` through secure terminal input or a secret manager. It is not a `platform-...` management Token and must not include `Bearer `, spaces or quotation marks. Never place it in prompts, screenshots, committed `.env` or workflow exports. `api_key=...` may be supplied from secure credential storage and is excluded from serialization.
|
|
39
|
+
|
|
40
|
+
## 3. Add the named native tools
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
from crewai import Agent
|
|
44
|
+
from seedance_crewai import SeedanceGenerateVideoTool, SeedanceRetrieveTaskTool
|
|
45
|
+
|
|
46
|
+
agent = Agent(
|
|
47
|
+
role="Seedance producer",
|
|
48
|
+
goal="Create the approved media, then retrieve the original task result",
|
|
49
|
+
backstory="Use Seedance through Ace Data Cloud within the user's approved budget.",
|
|
50
|
+
llm=your_configured_llm,
|
|
51
|
+
tools=[SeedanceGenerateVideoTool(), SeedanceRetrieveTaskTool()],
|
|
52
|
+
allow_delegation=False,
|
|
53
|
+
max_retry_limit=0,
|
|
54
|
+
)
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The two discoverable tool names are **Seedance by Ace Data Cloud - Generate Video** and **Seedance by Ace Data Cloud - Retrieve Task**. The Token goes in the environment, not a custom MCP header or agent prompt. Adding tools does not execute them. The caller approves paid requests; generation defaults to one use per instance to reduce duplicate submissions, which is not a funds cap or a permission system.
|
|
58
|
+
|
|
59
|
+
## 4. Service-specific input and first use
|
|
60
|
+
|
|
61
|
+
Structured `content`: text, image URL (+ first/last/reference role), audio URL (+ reference_audio), video URL (+ reference_video). Lowercase `resolution` (`480p/720p/1080p/4k`), `ratio`, optional duration -1..30, frames, seed, camerafixed, watermark, generate_audio and return_last_frame. Availability and valid combinations depend on the selected public model. This package does not expose web search, callbacks, expiry, priority or provider admin fields.
|
|
62
|
+
|
|
63
|
+
Check [the current model catalog and price](https://platform.acedata.cloud/models?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=seedancecrewai_package_first_use) before calling; model IDs are passed unchanged and no substitute model is added. The following values are examples from the pinned current API contract, not permanent defaults. **Executing generation is billable**; this guide does not run it.
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
import json
|
|
67
|
+
from seedance_crewai import SeedanceGenerateVideoTool, SeedanceRetrieveTaskTool
|
|
68
|
+
|
|
69
|
+
parameters = {
|
|
70
|
+
"model": "doubao-seedance-2-0-mini-260615",
|
|
71
|
+
"content": [
|
|
72
|
+
{
|
|
73
|
+
"type": "text",
|
|
74
|
+
"text": "A calm sunrise over a mountain lake"
|
|
75
|
+
}
|
|
76
|
+
],
|
|
77
|
+
"resolution": "480p",
|
|
78
|
+
"ratio": "16:9",
|
|
79
|
+
"generate_audio": False
|
|
80
|
+
}
|
|
81
|
+
# BILLABLE when executed; approve the current model and budget first.
|
|
82
|
+
submitted = SeedanceGenerateVideoTool().run(**parameters)
|
|
83
|
+
submitted = json.loads(submitted) # A ToolFailure must be handled before this step.
|
|
84
|
+
task_id = submitted["task_id"]
|
|
85
|
+
result = SeedanceRetrieveTaskTool().run(task_id=task_id, wait_seconds=240)
|
|
86
|
+
print(result)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The request submits once with `async=true`. accepted/pending is **not** a terminal result, even when an envelope has success=true. Preserve the original task ID; pending, timeouts or unknown submission outcomes do not authorize another generation. Bounded wait only queries that same ID, and can include an in-flight request timeout. Continue using Retrieve Task until terminal status. A true completed response requires the stored finished_at, service success and a valid target media URL. Nested failed states are treated as failure; a missing terminal media link is not fake success.
|
|
90
|
+
|
|
91
|
+
For a task you already own, run only this read-only example:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
uv run python examples/query_existing.py YOUR_EXISTING_TASK_ID
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
The query is `POST /seedance/tasks` with `action=retrieve,id=...`. A completed result returns `status=succeeded`, `success=true`, `task_id`, filtered `media_urls` and original `cost` in Credits when present. No raw original prompt, request, account/application identity, internal diagnostics or unfiltered body is returned. `cost` is not a new bill or USD amount. URL presence does not verify ongoing media playback.
|
|
98
|
+
|
|
99
|
+
## 5. Inspect execution and output
|
|
100
|
+
|
|
101
|
+

|
|
102
|
+
|
|
103
|
+
Official [CrewAI tracing reference](https://docs.crewai.com/en/observability/tracing), historical date marker 10/1/2025, capture version unspecified; retrieved 2026-10-18. Left: task and tool timeline; right: expanded Response output, not input. **Not this package running, not an Ace task and not a promised new GUI.** Trace account/auth/consent is optional and not enabled by this package. For your actual run inspect the named tool and its returned terminal fields; never expose Token or private media URLs in screenshots.
|
|
104
|
+
|
|
105
|
+
## Troubleshooting, privacy and cost
|
|
106
|
+
|
|
107
|
+
| Result | Action |
|
|
108
|
+
|---|---|
|
|
109
|
+
| 401 / 403 | Check full raw consumer Token, expiration, service entitlement, Allowed APIs and balance. A 403 is not always moderation. |
|
|
110
|
+
| 400 / schema rejection | Follow this service's fields, casing and model capability; unknown cross-service fields are rejected before network. |
|
|
111
|
+
| pending / no media yet | Query the same original task ID; never regenerate to poll. |
|
|
112
|
+
| 429 | Reduce concurrency and wait. One HTTP attempt per operation; your configured LLM/agent may retry separately. |
|
|
113
|
+
| Timeout / 5xx | Submission outcome can be unknown. Inspect request history before creating another task. |
|
|
114
|
+
| ToolFailure | Failed task or invalid terminal media; structured non-retryable result. Preserve task/trace ID for support, never Key. |
|
|
115
|
+
| Result URL cannot open | Check terminal success and your network; link existence alone is not playback evidence. |
|
|
116
|
+
|
|
117
|
+
The code is free; media generation and the LLM you configure have their current prices. No payment handler, fallback or automatic paid HTTP retry is added. Original Credits cost follows the API's current package/account rate and discounts; this package does not hard-code USD conversion. No install/CI count is presented as users or revenue.
|
|
118
|
+
|
|
119
|
+
Provided prompts/references and the consumer Token are sent to `api.acedata.cloud` over HTTPS. The package adds no telemetry or tracing; CrewAI/your LLM may have separate settings. [Privacy](https://github.com/AceDataCloud/SeedanceCrewAI/blob/322302879cf59f0e16e5f743fb5a1c76f90636dd/PRIVACY.md). [Source](https://github.com/AceDataCloud/SeedanceCrewAI) · [Issues](https://github.com/AceDataCloud/SeedanceCrewAI/issues) · dev@acedata.cloud
|
|
120
|
+
|
|
121
|
+
Development: `uv sync --group dev`, `uv run pytest`, `uv run ruff check .`, `uv build`. Paid HTTP is mocked in tests; native Agent/Task/Crew cycles use a deterministic local model fixture. See `tests/contract-source.json` for immutable service contract provenance and `tests/live-readonly-evidence.json` when an old-task check is available. No new paid request runs in CI.
|
|
122
|
+
|
|
123
|
+
The pinned source and preview.2 include explicit failed-state handling before finished_at. Historical preview.1 remains unchanged; use the pinned fixed version above.
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
{
|
|
2
|
+
"retrieved_at": "2026-10-18",
|
|
3
|
+
"images": [
|
|
4
|
+
{"file":"get-api-key-en.png","source_url":"https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/get-api-key-en.png","what_it_shows":"Redacted General application API Key copy and Manage Keys controls","limits":"Historical screenshot; no credentials visible; reused unchanged"},
|
|
5
|
+
{"file":"create-api-key-en.png","source_url":"https://raw.githubusercontent.com/AceDataCloud/SunoDify/8d3d03570e73324220f111f7fe343da0792a8071/_assets/tutorial/create-api-key-en.png","what_it_shows":"Create credential dialog","limits":"Historical example says Dify tutorial; README explains to use CrewAI Suno; reused unchanged"},
|
|
6
|
+
{"file":"official-crewai-tracing.png","source_url":"https://raw.githubusercontent.com/crewAIInc/crewAI/40bb2d3b586e8367d206090cc62df5242206008f/docs/images/crewai-tracing.png","official_page_url":"https://docs.crewai.com/v1.15.28/en/observability/tracing","what_it_shows":"Official CrewAI execution timeline and Response output","limits":"Historical date marker 10/1/2025; unknown capture version; not Ace runtime, not Suno package validation, not promised GUI"}
|
|
7
|
+
]
|
|
8
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"""Read-only query of a pre-existing Seedance task owned by your Key."""
|
|
2
|
+
|
|
3
|
+
import argparse
|
|
4
|
+
|
|
5
|
+
from seedance_crewai import SeedanceRetrieveTaskTool
|
|
6
|
+
|
|
7
|
+
p = argparse.ArgumentParser(description=__doc__)
|
|
8
|
+
p.add_argument("task_id")
|
|
9
|
+
a = p.parse_args()
|
|
10
|
+
print(SeedanceRetrieveTaskTool().run(task_id=a.task_id, wait_seconds=0))
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "crewai-seedance"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Seedance by Ace Data Cloud: native CrewAI video generation and same-task retrieval tools"
|
|
5
|
+
readme = "README.pypi.md"
|
|
6
|
+
requires-python = ">=3.10,<3.14"
|
|
7
|
+
license = "MIT"
|
|
8
|
+
authors = [{name = "Ace Data Cloud Dev", email = "dev@acedata.cloud"}]
|
|
9
|
+
keywords = ["crewai", "seedance", "video", "agents", "acedatacloud"]
|
|
10
|
+
dependencies = ["crewai>=1.15.28,<2", "httpx>=0.28,<1", "pydantic>=2.11,<3"]
|
|
11
|
+
[project.urls]
|
|
12
|
+
Homepage = "https://github.com/AceDataCloud/SeedanceCrewAI"
|
|
13
|
+
Repository = "https://github.com/AceDataCloud/SeedanceCrewAI"
|
|
14
|
+
Issues = "https://github.com/AceDataCloud/SeedanceCrewAI/issues"
|
|
15
|
+
[dependency-groups]
|
|
16
|
+
dev = ["pytest>=8,<10", "ruff==0.15.1", "build>=1,<2", "jsonschema>=4.23,<5"]
|
|
17
|
+
[build-system]
|
|
18
|
+
requires = ["hatchling"]
|
|
19
|
+
build-backend = "hatchling.build"
|
|
20
|
+
[tool.hatch.build.targets.wheel]
|
|
21
|
+
packages = ["src/seedance_crewai"]
|
|
22
|
+
[tool.pytest.ini_options]
|
|
23
|
+
testpaths = ["tests"]
|
|
24
|
+
[tool.ruff]
|
|
25
|
+
target-version = "py310"
|
|
26
|
+
[tool.ruff.lint]
|
|
27
|
+
select = ["E", "F", "I", "B", "UP"]
|
|
28
|
+
ignore = ["E501"]
|