Skip to main content

​
Seedance 2.0 API Documentation - Context & Notes

This file records architecture findings, correct API parameters, and test results for future reference when reloading context.

​
API Architecture (Critical)

​
Model Naming - Two-Level Structure

The API uses a two-level model naming system:
  • Top-level model: The workflow name → wan22-video-generation
  • inputs.model: The sub-model within the workflow → seedance-20
{
  "model": "wan22-video-generation",
  "inputs": {
    "model": "seedance-20",
    "prompt": "...",
    "resolution": "1280x720",
    "duration": "5s"
  }
}

​
Why NOT seedance20-video-generation as top-level model?

seedance20-video-generation exists in WORKFLOW_MAPPINGS (workflow-config.ts:185) but the task submission handler (task-submission.ts) does NOT have a case for it in the main switch statement. Using it causes: "Unsupported NewAPI workflow: seedance20-video-generation" The correct flow is:
  1. model: "wan22-video-generation" → switch case at task-submission.ts:35
  2. inputs.model: "seedance-20" → sub-routing at task-submission.ts:105
  3. This sets triggerTaskId = "seedance20-video-generation" internally

​
Response Model Field

The recordInfo endpoint returns model: order.toolId. For seedance-20 tasks, toolId is set to "seedance20-video-generation" (submit-task.ts:82-83). So:
  • Request: model: "wan22-video-generation", inputs.model: "seedance-20"
  • Response (recordInfo/webhook): model: "seedance20-video-generation"

​
Key Source Files

FilePurpose
packages/shared/client/workflow-config.tsWORKFLOW_MAPPINGS, params schemas
packages/workflow/services/newapi/task-submission.tsTask routing switch + sub-model handling
packages/api/modules/workflow/services/submit-task.tsOrder creation, toolId assignment
apps/web/app/api/v1/jobs/createTask/route.tsAPI endpoint, validation, auth
apps/web/app/api/v1/jobs/recordInfo/route.tsTask status query endpoint
apps/web/lib/auth/api-key-auth.tsAPI key authentication (SHA-256 hash)

​
Valid Parameters

​
Resolution (wan22-video-generation)

From workflow-config.ts params schema:
  • 720x720 (1:1)
  • 720x960 (3:4)
  • 960x720 (4:3)
  • 1280x720 (16:9)
  • 720x1280 (9:16)

​
inputs.model (wan22-video-generation sub-models)

  • z video (default)
  • sora2
  • sora2 pro
  • seedance-20
  • grok-imagine-video

​
videoInputMode (seedance-20 specific)

  • keyframe (40 credits/sec)
  • reference (90 credits/sec)

​
Duration

  • 4s to 15s

​
Task States

  • waiting → generating → success | fail

​
Credit Calculation

  • Text-to-video (seedance-20): 40 credits/sec
  • Image-to-video keyframe: 40 credits/sec
  • Image-to-video reference: 90 credits/sec
  • Formula: duration_seconds * rate
  • Credits are deducted at task creation, refunded on server error

​
Test Database

  • API Key: zimg_eQVFicFOpYTUOIJWhSPQq7hKZEPnnmLy
  • User: yixotieq@gmail.com (userId: cmk2ll9d400009wag8ncntbcq)
  • DB URL: postgresql://neondb_owner:npg_WKpk7hXH4san@ep-little-haze-adtefm8g-pooler.c-2.us-east-1.aws.neon.tech/neondb?sslmode=require&channel_binding=require
  • Key Hash: de00dff96908fc102a6d6a6e10ae9f0a1fc23bf91f9bcc0259957ed4db674efa

​
Testing

​
Test Scripts

  • test-api.sh - Bash script for parameter validation (9 tests)
  • examples/text_to_video.py - Python text-to-video example
  • examples/image_to_video.py - Python image-to-video example

​
Running Tests

# Against local dev server
SEEDANCE_API_KEY="zimg_eQVFicFOpYTUOIJWhSPQq7hKZEPnnmLy" ./test-api.sh http://localhost:3000

# Against production (needs production API key)
SEEDANCE_API_KEY="your_prod_key" ./test-api.sh

​
Known Issue

Local dev server (localhost:3000) may return 500 HTML for all requests due to environment/database configuration issues. Production endpoint works correctly for auth validation.

​
Documentation Status (2026-02-16)

  • All model names corrected to wan22-video-generation + inputs.model: "seedance-20"
  • Response examples correctly show model: "seedance20-video-generation" (toolId)
  • Branding updated: indigo theme (#6366f1), gradient text SVG logo, neon “S” favicon
  • All code examples (cURL, Node.js, Python) updated across all pages
  • Deployed via Cloudflare Worker proxy at seedance2-pro.com/docs
    • Worker Route: seedance2-pro.com/docs* (no slash before wildcard)
    • Proxies to: zimagevip.mintlify.dev

​
Cloudflare Worker

Route pattern must be docs* (not docs/*) to match both /docs and /docs/.... The Worker handles reverse proxy to Mintlify with redirect: "manual" to prevent 308 redirect loops.