Seedance 2.0

All modes, complete request fields and examples for this model.

ENDPOINT

POSThttps://platform-backend.topview.ai/api/v1/models/bytedance/seedance-2.0/text-to-video/predictions

Mode

duration=-1 selects automatic duration. The model and selected mode determine the output duration; it is not a fixed 15-second output. Mode-specific input requirements and duration constraints still apply.

The quoted price is an estimate; the final cost is based on actual usage. Automatic duration conservatively accounts for the model's 15-second maximum, selected mode, settings and reference media; source-video editing uses that mode's source-duration rules. Submission reserves funds; completion charges supplier-reported actual token usage at the rate locked in the quote and releases any unused reserved funds. Confirmed failure releases the full hold.

The reservation can be substantially higher than the final cost; sufficient available balance is required. Poll data.charged_usd for the final USD charge. data.billing_state=RESERVED is a temporary hold, CAPTURED means settled, and RELEASED means the full hold was returned after failure.

Authentication

Authenticate with your Platform API key in the Authorization header.

Authorization: Bearer YOUR_PLATFORM_KEYView API Keys

Your key needs models:generate and requests:read permissions. Only the following parameters are supported. Unsupported fields return 400 without a charge.

Submit Task

Submit model parameters directly; no estimate request is required. Save data.id to retrieve status, results and the final charge.

# Set TOPVIEW_API_PLATFORM_KEY once. Preserve REQUEST_KEY and input for uncertain retries.
# For a NEW task only, unset REQUEST_KEY first. Save data.id to resume GET only.
: "${TOPVIEW_API_PLATFORM_KEY:?Set TOPVIEW_API_PLATFORM_KEY first}"
export REQUEST_KEY="${REQUEST_KEY:-$(uuidgen)}"
curl --fail-with-body 'https://platform-backend.topview.ai/api/v1/models/bytedance/seedance-2.0/text-to-video/predictions' \
  -H "Authorization: Bearer $TOPVIEW_API_PLATFORM_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "content": [
    {
      "type": "text",
      "text": "A blue paper boat floating on a calm pond"
    }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9"
}'

Use a unique Idempotency-Key per task. Retry an uncertain submission with the same key and request. Python / JavaScript save input and idempotency key before submission in REQUEST_STATE (default .topview-request.json); keep this file private. Restart with the same file to recover, or set TASK_ID for GET-only recovery. Use a new state path for a new task. Polling retries network errors, 429 and 5xx with bounded backoff and Retry-After; after the retry limit or 30 minutes, resume the saved task ID.

Result Guide

Submit asynchronously and poll for results.

Save data.id after submission. HTTP 200 does not mean generation has completed.
Call GET with the original creating API key, requests:read and the corresponding mode permission. A new or rotated key cannot read the old key’s tasks. View Playground tasks in signed-in web history; authorized workspace members can also use web history after the original key expires or is revoked. Poll every 2–5 seconds and back off for long tasks or 429 / 5xx responses.
Keep polling created / processing tasks. On completed, read data.outputs. On failed, read data.error and stop polling.
payment_required means settlement needs more funds. amount_due_usd is the actual cost, additional_charge_usd is the amount above the original hold, and shortfall_usd is the eligible balance shortage. Top up the same workspace; settlement retries automatically without resubmitting. Estimates are not a cap: sufficient balance is automatically charged for the difference.
Read charged_usd and billing_state for settlement. Save results promptly because media URLs may expire. After a timeout, query the original task rather than creating a duplicate.

GEThttps://platform-backend.topview.ai/api/v1/predictions/REQUEST_ID

Replace REQUEST_ID with data.id. Poll data.status until completed or failed; successful results are in data.outputs.

curl --fail-with-body 'https://platform-backend.topview.ai/api/v1/predictions/REQUEST_ID' \
  -H "Authorization: Bearer $TOPVIEW_API_PLATFORM_KEY"

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "TASK_ID",
    "status": "completed",
    "outputs": [
      "https://example.com/generated-result"
    ],
    "charged_usd": "0.040000000000",
    "billing_state": "CAPTURED",
    "error": ""
  }
}

createdprocessingpayment_requiredcompletedfailed

data.charged_usd is the actual task cost in USD, returned as an exact decimal string. data.billing_state: RESERVED holds funds, CAPTURED settles the charge, and RELEASED returns the hold.

Schema

Request and response schemas for the selected mode.

Submit requests using official field names. The API path selects the model; no model identifier is needed in the request body. Required fields, defaults and mode-specific constraints are defined below.

Input schema

Common parameters match the Playground form. Use the API field path in request JSON; descriptions explain nested fields and media roles. — means no declared default, not null or zero.

Parameter / API path	Required	Type	Default	Options / limits	Description
`prompt`API: `content[].text`	Yes	`string`	—	min length 1; max length 10000	Describe the desired content. content item: type=text.
`aspect_ratio`API: `ratio`	No	`string`	Form: "16:9"; API: "adaptive"	"adaptive", "16:9", "9:16", "1:1", "4:3", "3:4", "21:9"	Output aspect ratio.
`resolution`	No	`string`	"720p"	"480p", "720p", "1080p"	Output resolution.
`duration`	No	`integer`	5	-1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15	Output duration in seconds. 4–15 seconds or -1 for automatic duration; default 5.
`generate_audio`	No	`boolean`	Form: true; API: —	true, false	Whether to generate output audio.

Advanced parameters and complete request structure

Parameter / API path	Required	Type	Default	Options / limits	Description
`content`	Yes	`object[]`	—	min items 1	Official multimodal content, forwarded without renaming.
`content[].type`	No	`string`	—	"text", "image_url", "video_url", "audio_url", "draft_task"	Content or media item type.
`content[].text`	No	`string`	—	—	Text to synthesize or process.
`content[].role`	No	`string`	—	—	Media role within the generation request.
`content[].image_url`	No	`object`	—	—	Image URL object.
`content[].image_url.url`	No	`string`	—	—	Official: 300–6000 px per side; width/height 0.4–2.5; each image under 30 MB. Platform input: PNG/JPEG/WebP only, at most 20 MiB (20,971,520 bytes), at most 40 megapixels. Checks run before a quote is created.
`content[].video_url`	No	`object`	—	—	Video URL object.
`content[].video_url.url`	No	`string`	—	—	Public media URL.
`content[].audio_url`	No	`object`	—	—	Audio URL object.
`content[].audio_url.url`	No	`string`	—	—	Public media URL.
`content[].draft_task`	No	`object`	—	—	Draft task reference.
`content[].draft_task.id`	No	`string`	—	—	A succeeded draft prediction ID owned by this Platform team and created by the same supplier/model.
`seed`	No	`integer`	—	—	Random seed.
`watermark`	No	`boolean`	—	true, false	Whether to add a watermark.
`safety_identifier`	No	`string`	—	—	Caller-provided safety identifier.
`return_last_frame`	No	`boolean`	—	true, false	Whether to return the final frame.
`service_tier`	No	`string`	—	—	Requested processing tier.
`execution_expires_after`	No	`integer`	—	—	Task execution expiry setting.
`priority`	No	`integer`	—	—	Task processing priority.
`draft`	No	`boolean`	—	true, false	Whether to request draft generation.
`camera_fixed`	No	`boolean`	—	true, false	Whether to use a fixed camera.
`output_format`	No	`string`	—	—	Output file format.
`omni_reference_task_type`	No	`string`	—	—	Reference-generation task type.
`frames`	No	`integer`	—	—	Requested number of video frames.
`tools`	No	`object[]`	—	—	Model tool configuration.

Raw input JSON Schema

{
  "type": "object",
  "properties": {
    "content": {
      "type": "array",
      "description": "Official multimodal content, forwarded without renaming.",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "text",
              "image_url",
              "video_url",
              "audio_url",
              "draft_task"
            ]
          },
          "text": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "image_url": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "description": "Official: 300–6000 px per side; width/height 0.4–2.5; each image under 30 MB. Platform input: PNG/JPEG/WebP only, at most 20 MiB (20,971,520 bytes), at most 40 megapixels. Checks run before a quote is created."
              }
            }
          },
          "video_url": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              }
            }
          },
          "audio_url": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              }
            }
          },
          "draft_task": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "A succeeded draft prediction ID owned by this Platform team and created by the same supplier/model."
              }
            }
          }
        }
      },
      "minItems": 1
    },
    "duration": {
      "type": "integer",
      "default": 5,
      "description": "4–15 seconds or -1 for automatic duration; default 5."
    },
    "resolution": {
      "type": "string",
      "enum": [
        "480p",
        "720p",
        "1080p"
      ],
      "default": "720p"
    },
    "ratio": {
      "type": "string",
      "enum": [
        "adaptive",
        "16:9",
        "9:16",
        "1:1",
        "4:3",
        "3:4",
        "21:9"
      ],
      "default": "adaptive"
    },
    "seed": {
      "type": "integer"
    },
    "watermark": {
      "type": "boolean"
    },
    "generate_audio": {
      "type": "boolean"
    },
    "safety_identifier": {
      "type": "string"
    },
    "return_last_frame": {
      "type": "boolean"
    },
    "service_tier": {
      "type": "string"
    },
    "execution_expires_after": {
      "type": "integer"
    },
    "priority": {
      "type": "integer"
    },
    "draft": {
      "type": "boolean"
    },
    "camera_fixed": {
      "type": "boolean"
    },
    "output_format": {
      "type": "string"
    },
    "omni_reference_task_type": {
      "type": "string"
    },
    "frames": {
      "type": "integer"
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "additionalProperties": false,
  "description": "Native request fields. The model route supplies model when omitted. Platform authentication, idempotency and asynchronous prediction responses remain unchanged.",
  "required": [
    "content"
  ]
}

Output schema

Task query response. Generation results are inside data. Nested field presence depends on the parent being returned.

Parameter / API path	Required	Type	Default	Options / limits	Description
`code`	Yes	`integer`	—	—	HTTP API envelope code. Inspect data.status for the task outcome.
`message`	Yes	`string`	—	—	API response message.
`data`	Yes	`object`	—	—	Prediction task details.
`data.id`	Yes	`string`	—	—	Platform task ID. Persist it before polling.
`data.created_at`	Yes	`string`	—	date-time	Task creation timestamp.
`data.code`	Yes	`integer`	—	—	0 for normal tasks; 402 when payment is required; 1403 for a failed task.
`data.execution_state`	Yes	`string`	—	—	Execution state; inspect status and billing_state before treating a task as settled.
`data.status`	Yes	`string`	—	"created", "processing", "payment_required", "completed", "failed"	Current task status.
`data.outputs`	Yes	`string[]`	—	—	Empty until settled successfully. HTTPS result URLs or image data; enable_base64_output returns raw Base64 without a data URI prefix.
`data.amount_due_usd`	No	`string`	—	—	Full actual cost in USD, present when status is payment_required.
`data.additional_charge_usd`	No	`string`	—	—	Actual cost minus the original reservation; present when payment is required.
`data.shortfall_usd`	No	`string`	—	—	Additional eligible balance needed at the latest settlement attempt. Top up this workspace; settlement retries automatically. No duplicate submission is needed.
`data.charged_usd`	Yes	`string`	—	—	Actual USD charge as an exact decimal string, not the reserved amount.
`data.billing_state`	Yes	`string`	—	"RESERVED", "CAPTURED", "RELEASED"	RESERVED is a temporary hold, not spending. CAPTURED is the final charge. RELEASED returns the full hold after failure; released funds are not recharge income.
`data.error`	Yes	`string`	—	—	Failure or payment-required description, otherwise an empty string.
`data.urls`	Yes	`object`	—	—	Task-related API URLs.
`data.urls.get`	Yes	`string`	—	uri	Authenticated polling URL. Use the original creating API key with requests:read and the corresponding mode permission.
`data.last_frame_url`	No	`string`	—	uri	Last-frame image URL when requested and returned, available only after settlement.

Raw output JSON Schema

{
  "type": "object",
  "required": [
    "code",
    "message",
    "data"
  ],
  "properties": {
    "code": {
      "type": "integer",
      "description": "HTTP API envelope code. Inspect data.status for the task outcome."
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "required": [
        "id",
        "created_at",
        "code",
        "execution_state",
        "status",
        "outputs",
        "charged_usd",
        "billing_state",
        "error",
        "urls"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Platform task ID. Persist it before polling."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "code": {
          "type": "integer",
          "description": "0 for normal tasks; 402 when payment is required; 1403 for a failed task."
        },
        "execution_state": {
          "type": "string",
          "description": "Execution state; inspect status and billing_state before treating a task as settled."
        },
        "status": {
          "type": "string",
          "enum": [
            "created",
            "processing",
            "payment_required",
            "completed",
            "failed"
          ]
        },
        "outputs": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Empty until settled successfully. HTTPS result URLs or image data; enable_base64_output returns raw Base64 without a data URI prefix."
        },
        "amount_due_usd": {
          "type": "string",
          "description": "Full actual cost in USD, present when status is payment_required."
        },
        "additional_charge_usd": {
          "type": "string",
          "description": "Actual cost minus the original reservation; present when payment is required."
        },
        "shortfall_usd": {
          "type": "string",
          "description": "Additional eligible balance needed at the latest settlement attempt. Top up this workspace; settlement retries automatically. No duplicate submission is needed."
        },
        "charged_usd": {
          "type": "string",
          "description": "Actual USD charge as an exact decimal string, not the reserved amount.",
          "pattern": "^[0-9]+(\\.[0-9]+)?$",
          "example": "0.040000000000"
        },
        "billing_state": {
          "type": "string",
          "description": "RESERVED is a temporary hold, not spending. CAPTURED is the final charge. RELEASED returns the full hold after failure; released funds are not recharge income.",
          "enum": [
            "RESERVED",
            "CAPTURED",
            "RELEASED"
          ]
        },
        "error": {
          "type": "string",
          "description": "Failure or payment-required description, otherwise an empty string."
        },
        "urls": {
          "type": "object",
          "required": [
            "get"
          ],
          "properties": {
            "get": {
              "type": "string",
              "format": "uri",
              "description": "Authenticated polling URL. Use the original creating API key with requests:read and the corresponding mode permission."
            }
          }
        },
        "last_frame_url": {
          "type": "string",
          "format": "uri",
          "description": "Last-frame image URL when requested and returned, available only after settlement."
        }
      }
    }
  }
}

Errors

HTTP	Meaning & recovery
`400`	Invalid or unsupported input. Check the schema.
`401`	Missing or invalid credentials. Check your API key.
`403`	Insufficient key permissions or model access.
`404`	Resource missing or inaccessible to this workspace.
`409`	Idempotency or version conflict. Check the original request.
`429`	Concurrency or rate limit reached. Wait and retry with backoff.
`5xx`	Temporary server error. Back off queries; keep the original idempotency key for uncertain submissions.

HTTP success does not guarantee generation success. Inspect data.status, data.error and billing_state.

Documentation