Seedream runs free in the PicassoIA playground, while the PicassoIA API takes a Bearer secret from your account and serves its own models to Node.js scripts. See which route fits, what the limits are, and run a working fetch example with polling and error handling.
Typing Seedream API Key into a search bar lands you in two very different places: ByteDance's own platform, and a crowd of sites that host the model for you. Which one you need depends on what you plan to ship. If you only want to see what Seedream produces, you need no credential at all. If you want a script that sends prompts and saves files, you need an account with an API provider, and providers differ a lot in price, limits and model access. This article lays out each route with facts checked against the official pages, points out where free access stops, and includes a Node.js script you can run today. One result worth stating up front: the PicassoIA API serves its own four models, and Seedream is not one of them, so the playground is where Seedream lives on PicassoIA.
Seedream is a family of image models from ByteDance, and the same model name shows up behind very different doors. Before you copy any code, pick the door that matches your goal.
| Route | What you need | Best for | The catch |
|---|---|---|---|
| Browser playground | A PicassoIA account | Testing prompts, references, 2K and 4K output | Manual, one generation at a time |
| Direct provider API | A credential from the provider's console | Apps that call Seedream itself | Pay-as-you-go billing once any trial quota ends |
| PicassoIA API | A pia_sk_ secret from your account | Scripts that use PicassoIA's own models | Seedream is not on its model list |
A quick rule of thumb: if the output is a handful of pictures for a post or a pitch, use the playground and stop there. If you are building a product whose users trigger Seedream directly, go to the provider and budget for pay-as-you-go billing from day one. If you are automating batches of thumbnails or edits with PicassoIA models, the PicassoIA API fits, as long as your plan allows it. Mixing routes is normal: draft in the playground, then move the winning prompt into a script.
The fastest way in is the browser. Seedream 5 Pro turns a text prompt, or up to 10 reference photos, into a 1K or 2K image. Seedream 4.5 pushes resolution further, with 2K and 4K output up to 4096 pixels and a batch mode that returns up to 15 related images in one run. Both model pages describe the browser experience as free and online, with no coding needed.
This route suits anyone who iterates by eye: change a lighting phrase, regenerate, compare the two results side by side. It does not suit a job that needs 500 images overnight, because every generation is a manual click.
The Seedream 5 Pro page itself cites BytePlus guidance, noting that prompts work best under 600 English words. BytePlus runs ModelArk, its model platform, and that console is where a direct Seedream credential comes from. According to the ModelArk documentation, new accounts receive a free inference trial quota that offsets pay-as-you-go inference fees. That quota is calculated separately for each model and shared under the primary account. Image generation goes through the image generation API, which exposes an /images/generations endpoint. Third-party integration docs list https://ark.ap-southeast.bytepluses.com/api/v3 as the default regional base URL.
💡 Copy the exact model or endpoint ID from your ModelArk console, not from a blog post, this one included. Identifiers change with each release, and a stale ID fails the request before it reaches the model.
I am not printing a direct-provider code sample here on purpose. The request shape and model IDs belong to BytePlus, they change, and a wrong guess wastes your afternoon. The Node.js example later in this article uses the PicassoIA API, where every endpoint and field below comes straight from its documentation.
Free access is real, but it has edges. Here is what each page claims and where those claims stop.
| Model | Output | Reference images | Notes from its page |
|---|---|---|---|
| Seedream 5 Pro | 1K or 2K, PNG or JPEG | Up to 10 | Prompts up to 4000 characters |
| Seedream 4.5 | 2K or 4K, custom sizes from 1024 to 4096 px | 1 to 14 | Up to 15 images per run in auto mode |
| Seedream 5 Lite | 2K | See page | Lighter sibling of Seedream 5 |
| Seedream 4 | 4K | See page | Earlier generation, still listed |
| Seedream 3 | 2K | See page | Oldest of the group |
Free in the browser says nothing about the API. The PicassoIA Image page advertises unlimited text-to-image generation with no per-image cap. The API documentation states that predictions are currently free and use no credits, yet the same documentation names the Infinite plan as the requirement, and a request without it returns 403 plan_required.
The pricing page lists API access on more than one tier, so two pages word this differently. Check your own plan before you build a product on top of it. The same caution applies to provider trial quotas: a trial is a starting balance, not a permanent allowance.
Limits can also attach to resolution, batch size or concurrency rather than to a flat count of pictures. Read the limits table in the API section before you design a batch job around a number you have only seen on a landing page.
Seedream 5 Pro on PicassoIA is quick to set up. Follow these steps in order:
1K is about 2 megapixels and 2K is about 4 megapixels. The default is 2K.match_input_image, copies the ratio of your first reference photo.
Three settings change results more than any adjective in the prompt:
1K for drafts and 2K for anything you will publish. Switch to Seedream 4.5 when you need 4K, because Seedream 5 Pro tops out at 2K.
💡 Describe the light, not the mood. "Low sun from the left, long shadows on the pavement" gives the model something to draw. "Dramatic atmosphere" gives it nothing.
Here is a prompt that uses these settings well, written for 2K at 16:9: A ceramic bowl of oranges on a linen cloth beside a window, low morning sun from the left, soft shadows stretching across the wooden table, 85mm lens look, shallow depth of field, visible weave in the linen. It names a subject, a light direction and a surface texture in under 50 words. Seedream 5 Pro accepts far more, but a short, concrete prompt is the best baseline: add one detail per run and keep the change only if the image improves.
The PicassoIA developer API authenticates with a Bearer secret that starts with pia_sk_. You create it from your account through the PicassoIA API page, and each account can hold two. Treat it like a password: keep it in an environment variable, never in a repository, and rotate it if it ever leaks into a screenshot or a log.
On Node 20.6 or newer you can keep the secret in a .env file and load it with node --env-file=.env generate.mjs, so it never lands in your shell history. Add .env to .gitignore before the first commit. If you deploy the script, set the variable in your host's secret manager instead of copying the file.
The API documentation lists four models:
picassoia/picassoia-image, for text-to-imagepicassoia/picassoia-image-editor-pro, for editing with 1 to 4 input imagespicassoia/picassoia-videopicassoia/seedance-2.5-lite, video with audioSeedream is not on that list. If a tutorial tells you to call a Seedream model with a pia_sk_ secret, check the model list in your own account first.
| Item | Value |
|---|---|
| Base URL | https://api.picassoia.com/v1 |
| Authentication | Authorization: Bearer pia_sk_… |
| Create a prediction | POST /v1/models/{owner}/{name}/predictions |
| Poll a prediction | GET /v1/predictions/{id} |
| Concurrent predictions | 5 per account, shared across all credentials and MCP generations |
| Request body | 10 MB maximum |
| Image as data URL | 5 MB each |
| Prompt | 4000 characters |
| Credentials per account | 2 |
You need Node 18 or newer, which ships a global fetch. Save the code as generate.mjs, export your secret as PICASSOIA_SECRET, and run node generate.mjs.
This helper follows the official documentation, with one change: the environment variable is named PICASSOIA_SECRET. It creates a prediction, sleeps for the interval the API suggests, polls until the job reaches a final status, and returns the output.
const API = 'https://api.picassoia.com/v1'
const headers = {
Authorization: `Bearer ${process.env.PICASSOIA_SECRET}`,
'Content-Type': 'application/json',
}
const sleep = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000))
async function run(model, input) {
const created = await fetch(`${API}/models/${model}/predictions`, {
method: 'POST',
headers,
body: JSON.stringify({ input }),
})
let prediction = await created.json()
if (!created.ok) throw new Error(`${prediction.code}: ${prediction.detail}`)
while (!['succeeded', 'failed', 'canceled'].includes(prediction.status)) {
await sleep(prediction.eta?.next_poll_in_seconds ?? 2)
prediction = await (await fetch(prediction.urls.get, { headers })).json()
}
if (prediction.status !== 'succeeded') throw new Error(prediction.error ?? prediction.status)
return prediction.output
}
Add this to the same file. It asks PicassoIA Image for one 16:9 JPEG and writes it to disk.
import { writeFile } from 'node:fs/promises'
const output = await run('picassoia/picassoia-image', {
prompt: 'A weathered fisherman mending a net on a grey pier at dawn, 35mm film look, soft side light',
aspect_ratio: '16:9',
num_outputs: 1,
output_format: 'jpg',
output_quality: 80,
})
const [url] = [].concat(output)
const image = await fetch(url)
await writeFile('result.jpg', Buffer.from(await image.arrayBuffer()))
console.log('Saved result.jpg from', url)
The [].concat(output) line accepts either a single URL or a list, so the script keeps working whichever shape the output takes.
PicassoIA Image Editor Pro needs a prompt and 1 to 4 images. The documentation lists data URLs of up to 5 MB each, so read the file and encode it:
import { readFile } from 'node:fs/promises'
const photo = await readFile('portrait.jpg')
const edited = await run('picassoia/picassoia-image-editor-pro', {
prompt: 'Replace the grey wall with warm red brick, keep the lighting and the face unchanged',
images: [`data:image/jpeg;base64,${photo.toString('base64')}`],
aspect_ratio: 'match_input_image',
})
console.log(edited)
When creation fails, the helper throws the API's own code and detail, which is why a missing plan shows up as plan_required instead of a vague network error. After creation, a prediction moves through five statuses:
| Status | What it means |
|---|---|
starting | The job exists and has produced nothing yet |
processing | The model is working on it |
succeeded | output holds the image URLs |
failed | error holds the reason |
canceled | The job was stopped, for example through POST /v1/predictions/{id}/cancel |
A failed prediction does not restart itself, so a retry means creating a new one. A thin wrapper handles transient failures and gives up at once on a plan error, which no amount of waiting will fix:
async function runWithRetry(model, input, attempts = 3) {
for (let i = 1; i <= attempts; i++) {
try {
return await run(model, input)
} catch (error) {
if (i === attempts || String(error.message).startsWith('plan_required')) throw error
await sleep(i * 5)
}
}
}
The limit is five concurrent predictions per account, and the count is shared across every credential and every MCP generation. A batch script and an open chat session draw from the same pool of five. A small worker pool keeps you under the cap and leaves one slot free:
async function pool(tasks, limit = 4) {
const results = []
let next = 0
const worker = async () => {
while (next < tasks.length) {
const i = next++
results[i] = await tasks[i]()
}
}
await Promise.all(Array.from({ length: limit }, worker))
return results
}
const prompts = ['a red bicycle against a pale wall', 'a lighthouse on a grey coast']
const images = await pool(
prompts.map((prompt) => () => run('picassoia/picassoia-image', { prompt, aspect_ratio: '16:9' })),
)
An image is rarely the last step. Two other PicassoIA collections slot straight into the pipeline: large language models before the image, and video after it.
A one-line idea gives the model little to work with. Paste it into Claude Sonnet 5 or Gemini 3.5 Flash and ask for structure:
Rewrite this idea as one image prompt of about 120 words with the subject, setting, light direction, lens and surface texture: "fisherman mending nets at dawn".
Send the result to Seedream 5 Pro in the playground or to PicassoIA Image through the script above. The four API models listed earlier do not include a chat model, so this step happens on the site.
Once a still looks right, Seedance 2.5 Lite can use it as the opening frame. Its page lists clips of 5 or 10 seconds at 480p or 720p, with synchronized audio, and describes unlimited generation for Wonder members. PicassoIA Video takes the same image-to-video input with a fixed 5 seconds at 24 frames per second. For stylized looks, PicassoIA also offers an effects category with hundreds of video effects, reachable from the all models page.
Describe motion in order, the way a director would call it: The fisherman pulls the net toward him, the camera drifts slowly to the right, gulls cross the pale sky, the soft light holds steady. One subject action, one camera move and one lighting note are enough for a short clip.
Pick one idea, one sentence long, and turn it into a picture today. Open Seedream 5 Pro on Picasso IA, paste a prompt, choose 2K and 16:9, and generate. Run the same prompt on Seedream 4.5 at 4K and compare the two files at full size.
When clicking stops being practical, create a PicassoIA API credential, paste the helper above into a file, and send your prompts through PicassoIA Image. Change one variable per run, keep the seeds you like, and let the five-slot limit set your pace. Every model mentioned here is one click away on the all models page.
