Seedream 5.0 Lite API: Fastest Image Generation Endpoint

REST API, Bearer auth, async generation, webhooks, native batching up to 50 images per request. Everything available in the Seedance web UI is also in the API. Here's the full reference with working Python and JavaScript examples you can copy into production today.

API Overview

The Seedream 5.0 Lite API provides programmatic access to the image generation pipeline on the Seedance platform. Everything in the web UI — text-to-image, deep thinking, style transfer, text rendering — is in the REST API.

The API follows REST conventions with JSON request and response bodies. Generation is asynchronous: submit a request, get a task ID, then either poll or receive a webhook when complete.

Full feature overview in our complete guide.

Base URL

https://api.seedance.it.com/v1

Key Characteristics

| Characteristic | Detail | |---|---| | Protocol | HTTPS REST | | Request format | JSON | | Response format | JSON | | Authentication | Bearer token | | Generation model | Asynchronous | | Average latency | 5-15 seconds | | Batch support | Yes (up to 50 per request) | | Webhook support | Yes | | SDKs | Python, JavaScript |

Authentication

Bearer token authentication. Generate your API key from the Seedance dashboard under Settings > API Keys.

Getting Your API Key

1. Sign up or log into your Seedance account
2. Navigate to Settings > API Keys
3. Click Generate New Key
4. Copy and securely store your key (shown only once)

Authentication Header

Authorization: Bearer YOUR_API_KEY

Testing Authentication

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.seedance.it.com/v1/account/credits

Response:

{
  "credits_remaining": 1050,
  "tier": "starter"
}

Single Image Endpoint

POST /v1/images/generate

Minimal Request

{
  "model": "seedream-5.0-lite",
  "prompt": "A serene mountain landscape at sunrise"
}

Full Request

{
  "model": "seedream-5.0-lite",
  "prompt": "Professional YouTube thumbnail with text 'TOP 10 TIPS' in bold red font, excited person on left, bright blue background",
  "aspect_ratio": "16:9",
  "deep_thinking": true,
  "style": "photorealistic",
  "webhook_url": "https://your-app.com/webhook/image-complete",
  "metadata": {
    "project": "youtube-thumbnails",
    "batch_id": "thumb-2026-04"
  }
}

Response

{
  "task_id": "img_abc123def456",
  "status": "processing",
  "model": "seedream-5.0-lite",
  "credits_charged": 7,
  "credits_remaining": 1043,
  "estimated_time_seconds": 10
}

Request Parameters

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | model | string | Yes | - | Model identifier: seedream-5.0-lite | | prompt | string | Yes | - | Text description (max 1000 chars) | | aspect_ratio | string | No | 1:1 | Output aspect ratio | | deep_thinking | boolean | No | false | Enable deep thinking mode | | style | string | No | auto | Style preset or description | | colors | array | No | - | Color palette (hex codes) | | webhook_url | string | No | - | URL for completion notification | | metadata | object | No | - | Custom metadata (returned with results) |

Aspect Ratios

| Value | Resolution | Use Case | |---|---|---| | 1:1 | 1024x1024 | Social media, product images | | 16:9 | 1360x768 | Thumbnails, presentations, banners | | 9:16 | 768x1360 | Stories, phone wallpapers | | 4:3 | 1184x888 | Blog images, email headers | | 3:4 | 888x1184 | Pinterest, portraits | | 3:2 | 1248x832 | Photography style |

Style Presets

| Preset | Description | |---|---| | auto | Model selects best style based on prompt | | photorealistic | Lifelike photography style | | digital-art | Clean digital illustration | | watercolor | Watercolor painting effect | | oil-painting | Classical oil painting | | anime | Japanese animation style | | minimalist | Clean, minimal design | | retro | Vintage/retro aesthetic |

Response Format

Polling for Results

GET /v1/images/{task_id}

Processing:

{
  "task_id": "img_abc123def456",
  "status": "processing",
  "progress": 0.65,
  "estimated_time_remaining": 5
}

Completed:

{
  "task_id": "img_abc123def456",
  "status": "completed",
  "image_url": "https://cdn.seedance.it.com/generated/img_abc123def456.png",
  "image_url_webp": "https://cdn.seedance.it.com/generated/img_abc123def456.webp",
  "width": 1024,
  "height": 1024,
  "model": "seedream-5.0-lite",
  "deep_thinking_used": true,
  "credits_charged": 7,
  "metadata": {
    "project": "youtube-thumbnails",
    "batch_id": "thumb-2026-04"
  },
  "created_at": "2026-04-10T14:30:00Z"
}

Image URL Expiration

Generated image URLs are valid for 24 hours. Download and store images in your own storage within this window.

Want text this clean? Try Seedream 5.0 Lite free →

Python Example

import requests
import time

API_KEY = "your_api_key_here"
BASE_URL = "https://api.seedance.it.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Submit generation request
response = requests.post(
    f"{BASE_URL}/images/generate",
    headers=headers,
    json={
        "model": "seedream-5.0-lite",
        "prompt": "A futuristic city skyline at sunset with flying cars",
        "aspect_ratio": "16:9",
        "deep_thinking": True
    }
)

task = response.json()
task_id = task["task_id"]
print(f"Task submitted: {task_id}")
print(f"Credits charged: {task['credits_charged']}")
print(f"Credits remaining: {task['credits_remaining']}")

# Poll for completion
while True:
    result = requests.get(
        f"{BASE_URL}/images/{task_id}",
        headers=headers
    ).json()

    if result["status"] == "completed":
        print(f"Image ready: {result['image_url']}")
        break
    elif result["status"] == "failed":
        print(f"Generation failed: {result.get('error', 'Unknown error')}")
        break

    time.sleep(2)

JavaScript Example

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.seedance.it.com/v1';

async function generateImage(prompt, options = {}) {
  const response = await fetch(`${BASE_URL}/images/generate`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'seedream-5.0-lite',
      prompt,
      aspect_ratio: options.aspectRatio || '1:1',
      deep_thinking: options.deepThinking || false,
      ...options
    })
  });

  const task = await response.json();
  console.log(`Task submitted: ${task.task_id}`);

  while (true) {
    const result = await fetch(
      `${BASE_URL}/images/${task.task_id}`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    ).then(r => r.json());

    if (result.status === 'completed') {
      return result;
    }
    if (result.status === 'failed') {
      throw new Error(result.error || 'Generation failed');
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

// Usage
const result = await generateImage(
  'A cozy coffee shop interior with warm lighting',
  { aspectRatio: '16:9', deepThinking: true }
);
console.log(`Image URL: ${result.image_url}`);

Downloading Generated Images

import requests

def download_image(image_url, filename):
    response = requests.get(image_url)
    with open(filename, 'wb') as f:
        f.write(response.content)
    print(f"Saved: {filename}")

download_image(result['image_url'], 'output/my_image.png')

Batch Generation Endpoint

For multiple images in a single request:

POST /v1/images/batch

Batch Request

{
  "generations": [
    {
      "prompt": "Minimalist logo design, blue circle with lightning bolt",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "1:1",
      "deep_thinking": true
    },
    {
      "prompt": "Professional headshot background, soft gradient",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "1:1",
      "deep_thinking": false
    },
    {
      "prompt": "YouTube thumbnail with text 'MUST WATCH' in red",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "16:9",
      "deep_thinking": true
    }
  ],
  "webhook_url": "https://your-app.com/webhook/batch-complete"
}

Batch Response

{
  "batch_id": "batch_xyz789",
  "status": "processing",
  "total_generations": 3,
  "total_credits_charged": 21,
  "credits_remaining": 1029
}

Polling Batch Status

GET /v1/images/batch/{batch_id}

{
  "batch_id": "batch_xyz789",
  "status": "completed",
  "results": [
    {
      "index": 0,
      "status": "completed",
      "task_id": "img_001",
      "image_url": "https://cdn.seedance.it.com/generated/img_001.png"
    },
    {
      "index": 1,
      "status": "completed",
      "task_id": "img_002",
      "image_url": "https://cdn.seedance.it.com/generated/img_002.png"
    },
    {
      "index": 2,
      "status": "completed",
      "task_id": "img_003",
      "image_url": "https://cdn.seedance.it.com/generated/img_003.png"
    }
  ]
}

Batch Limits

| Limit | Value | |---|---| | Max generations per batch | 50 | | Max concurrent batches | 5 | | Max prompt length | 1000 characters | | Batch timeout | 5 minutes |

For batch workflows, see our bulk generation guide.

Webhook Integration

Webhooks eliminate polling. When generation completes, the API POSTs to your URL.

Webhook Payload

{
  "event": "image.completed",
  "task_id": "img_abc123def456",
  "batch_id": "batch_xyz789",
  "status": "completed",
  "image_url": "https://cdn.seedance.it.com/generated/img_abc123def456.png",
  "model": "seedream-5.0-lite",
  "credits_charged": 7,
  "metadata": {
    "project": "youtube-thumbnails"
  },
  "created_at": "2026-04-10T14:30:00Z"
}

Handler Example (Python/Flask)

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/webhook/image-complete', methods=['POST'])
def handle_image_webhook():
    data = request.json

    if data['event'] == 'image.completed':
        task_id = data['task_id']
        image_url = data['image_url']
        metadata = data.get('metadata', {})

        # Download image
        img_response = requests.get(image_url)
        filename = f"images/{metadata.get('project', 'default')}/{task_id}.png"
        with open(filename, 'wb') as f:
            f.write(img_response.content)

        # Update your database
        update_generation_record(task_id, filename)

        print(f"Image saved: {filename}")

    elif data['event'] == 'image.failed':
        print(f"Generation failed: {data.get('error')}")

    return jsonify({'status': 'ok'}), 200

Webhook Security

Verify webhook authenticity via the X-Seedance-Signature header:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Deep Thinking Mode

Controlled by the deep_thinking boolean parameter. Enabled, the model performs additional reasoning before generation.

When to Enable

| Scenario | Recommendation | |---|---| | Simple single-subject images | false | | Complex multi-element scenes | true | | Images with text | true | | Specific spatial layouts | true | | Abstract/conceptual imagery | true | | Batch of simple images | false (max throughput) |

Performance Impact

| Mode | Avg Generation Time | Quality Improvement | |---|---|---| | Standard (false) | ~5-10 seconds | Baseline | | Deep thinking (true) | ~8-15 seconds | Significant for complex prompts |

Deep thinking adds ~3-5 seconds but costs zero additional credits.

Error Handling

Error Response Format

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete this generation. Required: 7, Available: 3",
    "status": 402
  }
}

Error Codes

| Code | Status | Description | Resolution | |---|---|---|---| | invalid_api_key | 401 | API key invalid or expired | Regenerate in dashboard | | insufficient_credits | 402 | Not enough credits | Purchase more at /pricing | | invalid_model | 400 | Model identifier not recognized | Use seedream-5.0-lite | | invalid_prompt | 400 | Prompt empty or too long | Check length (max 1000) | | invalid_aspect_ratio | 400 | Aspect ratio not supported | Use supported values | | rate_limited | 429 | Too many requests | Implement backoff | | content_policy | 400 | Prompt violates policy | Modify prompt | | generation_failed | 500 | Internal generation error | Retry the request | | batch_too_large | 400 | Batch exceeds 50 items | Split into smaller batches |

Retry Strategy

import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                f"{BASE_URL}/images/generate",
                headers=headers,
                json={
                    "model": "seedream-5.0-lite",
                    "prompt": prompt
                }
            )

            if response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 5))
                time.sleep(retry_after)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff

Rate Limits and Best Practices

Rate Limits by Tier

| Tier | Requests/Minute | Concurrent | Batch Size | |---|---|---|---| | Free | 10 | 2 | 5 | | Starter | 30 | 5 | 20 | | Popular | 60 | 10 | 30 | | Pro | 120 | 20 | 50 | | Enterprise | 240 | 50 | 50 |

Best Practices

1. Use webhooks over polling — more efficient
2. Batch when possible — one batch request beats 50 individual requests
3. Exponential backoff — handle rate limits gracefully
4. Cache results — store image URLs and metadata in your database
5. Download promptly — image URLs expire after 24 hours
6. Monitor credit balance — check credits_remaining to avoid interruptions
7. Use metadata — tag generations with project IDs for tracking
8. Handle errors gracefully — not every generation succeeds

SDK Installation

Python:

pip install seedance

from seedance import SeedanceClient

client = SeedanceClient(api_key="your_key")
result = client.images.generate(
    model="seedream-5.0-lite",
    prompt="A beautiful sunset",
    deep_thinking=True
)

JavaScript:

npm install @seedance/sdk

import { SeedanceClient } from '@seedance/sdk';

const client = new SeedanceClient({ apiKey: 'your_key' });
const result = await client.images.generate({
    model: 'seedream-5.0-lite',
    prompt: 'A beautiful sunset',
    deepThinking: true
});

Common Integration Patterns

CMS Integration

Generate featured images automatically on post creation:

@app.route('/cms/webhook/new-post', methods=['POST'])
def handle_new_post():
    post = request.json

    result = generate_image(
        prompt=f"Blog header image for article about {post['title']}, "
               f"professional editorial style, 16:9",
        aspect_ratio="16:9",
        deep_thinking=True,
        metadata={"post_id": post["id"]}
    )

    update_post_featured_image(post["id"], result["image_url"])

E-Commerce Product Images

def generate_product_images(product):
    prompts = [
        f"Product photo of {product.name}, white background, studio lighting, 1:1",
        f"Lifestyle photo of {product.name} in use, natural setting, 16:9",
        f"Product detail close-up of {product.name}, macro photography, 1:1"
    ]

    batch = client.images.batch_generate(
        generations=[
            {"model": "seedream-5.0-lite", "prompt": p}
            for p in prompts
        ]
    )

    return batch

Social Media Automation

def generate_weekly_social_content(brand, topics):
    generations = []
    for topic in topics:
        generations.append({
            "model": "seedream-5.0-lite",
            "prompt": f"{brand.style_prefix} {topic}, social media post, 1:1",
            "aspect_ratio": "1:1",
            "deep_thinking": True,
            "metadata": {"topic": topic, "platform": "instagram"}
        })

    return client.images.batch_generate(generations=generations)

---

The Seedream 5.0 Lite API is the fastest path from text prompt to generated image with full support for deep thinking, batch generation, and webhook integration.

Get your API key → — 50 free credits, generate your key from Settings > API Keys, start building in minutes.