Get started
Quick Start
Create an API key, submit your first generation, and retrieve the result.
1. Create an API key
Sign in, choose your workspace and open API keys. Create a key with models:generate and requests:read permissions, then select the model and the modes you want to use, such as Seedance 2.5 → Text to Video. No internal model ID is needed. Store the key on your server. Ensure the workspace has enough available balance for generation.
export TOPVIEW_API_PLATFORM_KEY="YOUR_PLATFORM_KEY"2. Choose a model
Browse Video or Image in this documentation. Each model page includes its endpoint, supported modes, parameter tables and runnable examples. The example below uses Seedance 2.0 Mini text-to-video.
3. Submit a task
Submit model parameters directly with a unique Idempotency-Key for this task. No estimate request is required. The server handles the temporary balance reservation. Save data.id as TASK_ID. If a request times out, retry with the same key and unchanged input rather than creating another task.
curl "https://platform-backend.topview.ai/api/v1/models/bytedance/seedance-2.0-mini/text-to-video/predictions" -H "Authorization: Bearer $TOPVIEW_API_PLATFORM_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: YOUR_UNIQUE_TASK_KEY" -d '{"content":[{"type":"text","text":"A paper boat floating on a calm pond"}],"resolution":"480p","duration":5,"ratio":"16:9"}'4. Get the result
Use the original creating API key with requests:read and the task mode permission. A rotated or newly created key cannot query an old key’s task. View Playground tasks, or API tasks whose key is no longer active, in authorized workspace web history. Model-page Python and JavaScript examples persist the request in REQUEST_STATE before submitting; restart with the same file or set TASK_ID for GET-only recovery. Keep the state file private and use a new path for each new task. Poll every 2–5 seconds with backoff for long-running tasks or 429 / 5xx responses. On completed, read data.outputs and data.charged_usd (the actual charge in USD, returned as an exact decimal string). data.billing_state = CAPTURED confirms final settlement. Save the generated media before URLs expire. On failed, inspect data.error. Fetch the task again to obtain fresh result URLs. Results are retrieved by polling.
| data.status | Action |
|---|---|
| created | Task accepted; continue polling. |
| processing | Generation or reconciliation is in progress; continue polling. |
| completed | Read outputs and final billing fields. |
| failed | Read error; do not keep polling. |
curl "https://platform-backend.topview.ai/api/v1/predictions/TASK_ID" -H "Authorization: Bearer $TOPVIEW_API_PLATFORM_KEY"