@runapi.ai/seedream 0.2.1 → 0.2.4
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.
- package/package.json +2 -2
- package/skills/seedream/README.md +34 -2
- package/skills/seedream/SKILL.md +52 -175
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@runapi.ai/seedream",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.4",
|
|
4
4
|
"description": "RunAPI Seedream SDK for JavaScript, Ruby, and Go",
|
|
5
5
|
"main": "./dist/index.js",
|
|
6
6
|
"module": "./dist/index.mjs",
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
"clean": "rm -rf dist"
|
|
29
29
|
},
|
|
30
30
|
"dependencies": {
|
|
31
|
-
"@runapi.ai/core": "^0.2.
|
|
31
|
+
"@runapi.ai/core": "^0.2.4"
|
|
32
32
|
},
|
|
33
33
|
"devDependencies": {
|
|
34
34
|
"@types/node": "^20.0.0",
|
|
@@ -1,4 +1,25 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://github.com/runapi-ai/seedream">
|
|
3
|
+
<h3 align="center">Seedream API Skill for RunAPI</h3>
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
Install this agent skill, inspect Seedream fields, then run jobs through the RunAPI CLI.
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<a href="https://runapi.ai/models/seedream"><strong>Model Reference</strong></a> · <a href="https://github.com/runapi-ai/cli"><strong>CLI</strong></a> · <a href="https://github.com/runapi-ai/seedream-sdk"><strong>SDK</strong></a>
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<div align="center">
|
|
16
|
+
|
|
17
|
+
[](https://www.skills.sh/runapi-ai/seedream/seedream)
|
|
18
|
+
[](https://clawhub.ai/runapi-ai/runapi-seedream)
|
|
19
|
+
[](https://github.com/runapi-ai/seedream/blob/main/LICENSE)
|
|
20
|
+
|
|
21
|
+
</div>
|
|
22
|
+
<br/>
|
|
2
23
|
|
|
3
24
|
Generate and edit images with Seedream 4.5 and 5-lite text-to-image, image-to-image, and image editing. This skill helps Claude Code, Codex, Gemini CLI, Cursor, and 50+ agents integrate Seedream through RunAPI.
|
|
4
25
|
|
|
@@ -10,7 +31,18 @@ The canonical agent file is `skills/seedream/SKILL.md`.
|
|
|
10
31
|
npx skills add runapi-ai/seedream -g
|
|
11
32
|
```
|
|
12
33
|
|
|
13
|
-
Or
|
|
34
|
+
Or paste this prompt to your AI agent:
|
|
35
|
+
|
|
36
|
+
```text
|
|
37
|
+
Install the seedream skill for me:
|
|
38
|
+
|
|
39
|
+
1. Clone https://github.com/runapi-ai/seedream
|
|
40
|
+
2. Copy the skills/seedream/ directory into your
|
|
41
|
+
user-level skills directory (e.g. ~/.claude/skills/
|
|
42
|
+
for Claude Code, ~/.codex/skills/ for Codex).
|
|
43
|
+
3. Verify that SKILL.md is present.
|
|
44
|
+
4. Confirm the install path when done.
|
|
45
|
+
```
|
|
14
46
|
|
|
15
47
|
## Quick example
|
|
16
48
|
|
package/skills/seedream/SKILL.md
CHANGED
|
@@ -1,202 +1,79 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: seedream
|
|
3
|
-
description: Generate and edit images
|
|
4
|
-
documentation: https://runapi.ai/models/seedream
|
|
5
|
-
provider_page: https://runapi.ai/providers/bytedance
|
|
6
|
-
catalog: https://runapi.ai/models
|
|
3
|
+
description: Generate and edit images with Seedream through RunAPI. Use when the user asks an agent to create, edit, or transform images with Seedream. Default to the RunAPI CLI for one-off generation; use SDKs only when the user is integrating RunAPI into an app or backend.
|
|
4
|
+
documentation: https://runapi.ai/models/seedream.md
|
|
5
|
+
provider_page: https://runapi.ai/providers/bytedance.md
|
|
6
|
+
catalog: https://runapi.ai/models.md
|
|
7
|
+
metadata:
|
|
8
|
+
openclaw:
|
|
9
|
+
homepage: https://runapi.ai/models/seedream
|
|
10
|
+
requires:
|
|
11
|
+
bins:
|
|
12
|
+
- runapi
|
|
13
|
+
install:
|
|
14
|
+
- kind: brew
|
|
15
|
+
formula: runapi-ai/tap/runapi
|
|
16
|
+
bins:
|
|
17
|
+
- runapi
|
|
18
|
+
envVars:
|
|
19
|
+
- name: RUNAPI_API_KEY
|
|
20
|
+
required: false
|
|
21
|
+
description: Optional RunAPI API key; agents should prefer environment auth or saved CLI config. Browser login is interactive fallback only.
|
|
7
22
|
---
|
|
8
|
-
# @runapi.ai/seedream — RunAPI.ai Seedream image generation
|
|
9
23
|
|
|
10
|
-
|
|
24
|
+
# Seedream on RunAPI
|
|
11
25
|
|
|
12
|
-
|
|
26
|
+
Generate and edit images with Seedream through RunAPI. The default path for one-off agent tasks is the `runapi` CLI; SDKs are for application integration.
|
|
13
27
|
|
|
14
|
-
|
|
28
|
+
## Routing decision
|
|
15
29
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
Set your API key in the environment:
|
|
21
|
-
|
|
22
|
-
```dotenv
|
|
23
|
-
# .env
|
|
24
|
-
RUNAPI_API_KEY=runapi_xxx # get one at https://runapi.ai/settings/api_keys
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
```ts
|
|
28
|
-
import { SeedreamClient } from '@runapi.ai/seedream';
|
|
29
|
-
|
|
30
|
-
// The SDK reads RUNAPI_API_KEY from the environment automatically.
|
|
31
|
-
const client = new SeedreamClient();
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
Pass `{ apiKey }` explicitly if you manage secrets differently. `baseUrl` defaults to `https://runapi.ai`; override only for local development.
|
|
35
|
-
|
|
36
|
-
## Core recipe — text to image
|
|
37
|
-
|
|
38
|
-
```ts
|
|
39
|
-
const result = await client.textToImage.run({
|
|
40
|
-
model: 'seedream-4.5-text-to-image',
|
|
41
|
-
prompt: 'A cinematic portrait of a traveler in the rain',
|
|
42
|
-
aspect_ratio: '16:9',
|
|
43
|
-
quality: 'basic',
|
|
44
|
-
});
|
|
45
|
-
|
|
46
|
-
const url = result.images[0].url;
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
`run()` creates the task, auto-polls, and resolves only when the task completes — `images[0].url` is guaranteed on the resolved value. On failure it throws `TaskFailedError`; on polling timeout it throws `TaskTimeoutError`. Use `run()` for scripts and short-lived processes. For request handlers, split it:
|
|
50
|
-
|
|
51
|
-
```ts
|
|
52
|
-
const { id } = await client.textToImage.create({
|
|
53
|
-
model: 'seedream-4.5-text-to-image',
|
|
54
|
-
prompt: '...',
|
|
55
|
-
aspect_ratio: '1:1',
|
|
56
|
-
quality: 'basic',
|
|
57
|
-
});
|
|
58
|
-
// return 202 immediately; fetch later:
|
|
59
|
-
const status = await client.textToImage.get(id);
|
|
60
|
-
if (status.status === 'completed') { /* ... */ }
|
|
61
|
-
```
|
|
30
|
+
- One-off generation, editing, or transformation for the user → use the **CLI path** with the `runapi` binary.
|
|
31
|
+
- Building an app, backend, worker, library, or production codebase → use the **SDK integration path**.
|
|
62
32
|
|
|
63
|
-
|
|
33
|
+
## CLI path
|
|
64
34
|
|
|
65
|
-
`
|
|
35
|
+
The `runapi` binary is the runtime dependency. Run `runapi auth status` first. For agents and headless runs, prefer `RUNAPI_API_KEY` or import it into saved config with `printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -`. Use `runapi login` only when the user explicitly wants interactive browser auth.
|
|
66
36
|
|
|
67
|
-
|
|
68
|
-
await client.textToImage.run(params, { maxWaitMs: 5 * 60_000, pollIntervalMs: 2_000 });
|
|
69
|
-
```
|
|
37
|
+
Inspect the available actions and request fields with CLI help:
|
|
70
38
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
Provide one or more `image_urls` with the matching model:
|
|
76
|
-
|
|
77
|
-
```ts
|
|
78
|
-
// 4.5 edit — in-place editImage guided by a prompt
|
|
79
|
-
await client.textToImage.run({
|
|
80
|
-
model: 'seedream-4.5-edit',
|
|
81
|
-
prompt: 'Change the background to a sunset beach',
|
|
82
|
-
image_urls: ['https://cdn.example.com/source.jpg'],
|
|
83
|
-
aspect_ratio: '16:9',
|
|
84
|
-
quality: 'high',
|
|
85
|
-
});
|
|
86
|
-
|
|
87
|
-
// 5-lite image-to-image — style/content transfer from a reference
|
|
88
|
-
await client.textToImage.run({
|
|
89
|
-
model: 'seedream-5-lite-image-to-image',
|
|
90
|
-
prompt: 'In the style of a traditional ink painting',
|
|
91
|
-
image_urls: ['https://cdn.example.com/portrait.jpg'],
|
|
92
|
-
aspect_ratio: '3:4',
|
|
93
|
-
quality: 'basic',
|
|
94
|
-
});
|
|
39
|
+
```shell
|
|
40
|
+
runapi seedream --help
|
|
41
|
+
runapi seedream text-to-image --help
|
|
95
42
|
```
|
|
96
43
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
| `model` | Use case |
|
|
100
|
-
|---|---|
|
|
101
|
-
| `seedream-4.5-text-to-image` | High-quality text-to-image. |
|
|
102
|
-
| `seedream-4.5-edit` | Prompt-guided editImage on one or more source images. |
|
|
103
|
-
| `seedream-5-lite-text-to-image` | Faster, cheaper text-to-image. |
|
|
104
|
-
| `seedream-5-lite-image-to-image` | Faster image-to-image transfer. |
|
|
105
|
-
|
|
106
|
-
`aspect_ratio` values: `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9`. `quality`: `basic` or `high`.
|
|
107
|
-
|
|
108
|
-
Exact credit costs per model are shown at https://runapi.ai/pricing and in the dashboard — do not hardcode prices in application code.
|
|
109
|
-
|
|
110
|
-
## Callbacks (webhooks)
|
|
111
|
-
|
|
112
|
-
Pass `callback_url` on `create()` (or any `run()` call) and RunAPI will POST the final payload to you:
|
|
44
|
+
Run a one-off task (synchronous — polls until the task completes):
|
|
113
45
|
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
model: 'seedream-4.5-text-to-image',
|
|
117
|
-
prompt: '...',
|
|
118
|
-
aspect_ratio: '1:1',
|
|
119
|
-
quality: 'basic',
|
|
120
|
-
callback_url: 'https://your.app/webhooks/runapi/seedream',
|
|
121
|
-
});
|
|
46
|
+
```shell
|
|
47
|
+
runapi seedream text-to-image --input-file request.json
|
|
122
48
|
```
|
|
123
49
|
|
|
124
|
-
|
|
50
|
+
Submit asynchronously and poll separately:
|
|
125
51
|
|
|
126
|
-
```
|
|
127
|
-
|
|
52
|
+
```shell
|
|
53
|
+
runapi seedream text-to-image --async --input-file request.json
|
|
54
|
+
runapi wait <task-id> --service seedream --action text-to-image
|
|
128
55
|
```
|
|
129
56
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
- `X-Callback-Id` — UUID, store to make handler idempotent
|
|
133
|
-
- `X-Callback-Timestamp` — unix seconds, reject if `|now - ts| > 300`
|
|
134
|
-
- `X-Callback-Signature` — base64 HMAC-SHA256 over `` `${id}.${ts}.${rawBody}` `` using the base64-decoded secret
|
|
135
|
-
|
|
136
|
-
```ts
|
|
137
|
-
import crypto from 'node:crypto';
|
|
138
|
-
|
|
139
|
-
function verify(raw: string, id: string, ts: string, sig: string, secret: string) {
|
|
140
|
-
const key = Buffer.from(secret, 'base64');
|
|
141
|
-
const mac = crypto.createHmac('sha256', key)
|
|
142
|
-
.update(`${id}.${ts}.${raw}`)
|
|
143
|
-
.digest('base64');
|
|
144
|
-
return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(sig));
|
|
145
|
-
}
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
Reply `2xx` within 10s; any non-2xx triggers retries.
|
|
149
|
-
|
|
150
|
-
## Errors
|
|
151
|
-
|
|
152
|
-
All errors are re-exported from `@runapi.ai/core`. Always `instanceof` — never string-match messages.
|
|
153
|
-
|
|
154
|
-
| Error | Status | Action |
|
|
155
|
-
|---|---|---|
|
|
156
|
-
| `AuthenticationError` | 401 | abort; surface "reconnect your API key" |
|
|
157
|
-
| `InsufficientCreditsError` | 402 | prompt user to top up at runapi.ai/billing |
|
|
158
|
-
| `ValidationError` | 400 / 422 | fix params; do not retry |
|
|
159
|
-
| `RateLimitError` | 429 | sleep `err.retryAfterMs`, then retry |
|
|
160
|
-
| `ServiceUnavailableError` | 503 / 455 | retry with backoff; transient service issue |
|
|
161
|
-
| `TaskFailedError` | — | show `err.details` to user; do not auto-retry |
|
|
162
|
-
| `TaskTimeoutError` | — | re-poll with `textToImage.get(id)` |
|
|
163
|
-
|
|
164
|
-
```ts
|
|
165
|
-
import { InsufficientCreditsError, TaskFailedError } from '@runapi.ai/seedream';
|
|
166
|
-
|
|
167
|
-
try {
|
|
168
|
-
await client.textToImage.run({
|
|
169
|
-
model: 'seedream-4.5-text-to-image',
|
|
170
|
-
prompt: '...',
|
|
171
|
-
aspect_ratio: '1:1',
|
|
172
|
-
quality: 'basic',
|
|
173
|
-
});
|
|
174
|
-
} catch (err) {
|
|
175
|
-
if (err instanceof InsufficientCreditsError) { /* surface top-up CTA */ }
|
|
176
|
-
else if (err instanceof TaskFailedError) { /* show err.details */ }
|
|
177
|
-
else throw err;
|
|
178
|
-
}
|
|
179
|
-
```
|
|
57
|
+
Available actions: `text-to-image`.
|
|
180
58
|
|
|
181
|
-
##
|
|
59
|
+
## SDK integration path
|
|
182
60
|
|
|
183
|
-
|
|
184
|
-
- Edit and image-to-image models require `image_urls` (an array, even for a single image).
|
|
185
|
-
- `nsfw_checker` only applies to `seedream-5-lite-*` models.
|
|
186
|
-
- `callback_url` must be reachable from the public internet. `localhost` / `127.0.0.1` URLs will never fire — use a tunnel (cloudflared, ngrok, tailscale funnel) when developing locally.
|
|
61
|
+
When integrating Seedream into an app, backend, worker, or library — not for one-off tasks — use a RunAPI SDK package:
|
|
187
62
|
|
|
188
|
-
|
|
63
|
+
- JavaScript / TypeScript: `@runapi.ai/seedream`
|
|
64
|
+
- Ruby: `runapi-seedream`
|
|
65
|
+
- Go: `github.com/runapi-ai/seedream-sdk/go`
|
|
189
66
|
|
|
190
|
-
|
|
67
|
+
## References
|
|
191
68
|
|
|
192
|
-
|
|
69
|
+
- Model overview, pricing, and rate limits: https://runapi.ai/models/seedream.md
|
|
70
|
+
- Provider comparison: https://runapi.ai/providers/bytedance.md
|
|
71
|
+
- Full model catalog: https://runapi.ai/models.md
|
|
193
72
|
|
|
194
|
-
|
|
73
|
+
## Variants
|
|
195
74
|
|
|
196
|
-
|
|
197
|
-
- [4.5
|
|
198
|
-
- [
|
|
199
|
-
- [5 lite
|
|
200
|
-
- [5 lite image to image](https://runapi.ai/models/seedream/5-lite-image-to-image)
|
|
75
|
+
- [4.5 text to image](https://runapi.ai/models/seedream/4.5-text-to-image.md)
|
|
76
|
+
- [4.5 edit](https://runapi.ai/models/seedream/4.5-edit.md)
|
|
77
|
+
- [5 lite text to image](https://runapi.ai/models/seedream/5-lite-text-to-image.md)
|
|
78
|
+
- [5 lite image to image](https://runapi.ai/models/seedream/5-lite-image-to-image.md)
|
|
201
79
|
|
|
202
|
-
Compare Seedream with other Bytedance models at https://runapi.ai/providers/bytedance. Browse every RunAPI model and skill at https://runapi.ai/models. SDK repository: https://github.com/runapi-ai/seedream-sdk. Skill repository: https://github.com/runapi-ai/seedream.
|