Video Generation and Material Library API

export TOS_API_KEY="gk_YOUR_KEY"

Authorization: Bearer gk_YOUR_KEY
Content-Type: application/json

POST /api/material?Action={Action}&Version=2024-01-01

{
  "ResponseMetadata": {
    "RequestId": "2026062317822087486485654725234569",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {}
}

export TOS_API_KEY="gk_YOUR_KEY"
export BASE_URL="https://ai.tos.run"

curl --noproxy '*' -X POST "$BASE_URL/api/material?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "product-references",
    "Description": "product reference assets"
  }'

curl --noproxy '*' -X POST "$BASE_URL/api/material?Action=GetAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Id":"group-20260623180314-r2rc7"}'

curl --noproxy '*' -X POST "$BASE_URL/api/material?Action=ListAssetGroups&Version=2024-01-01" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "PageNumber": 1,
    "PageSize": 10,
    "Filter": {"GroupType": "AIGC"}
  }'

curl --noproxy '*' -X POST "$BASE_URL/api/material?Action=UpdateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Id": "group-20260623180314-r2rc7",
    "Name": "updated-product-references",
    "Description": "updated description"
  }'

curl --noproxy '*' -X POST "$BASE_URL/api/material?Action=DeleteAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Id":"group-20260623180314-r2rc7"}'

curl --noproxy '*' -X POST "$BASE_URL/api/material?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "group-20260623180314-r2rc7",
    "Name": "person-reference",
    "AssetType": "Image",
    "URL": "YOUR_PUBLIC_IMAGE_URL"
  }'

curl --noproxy '*' -X POST "$BASE_URL/api/material?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Id":"asset-20260623180317-8sxkd"}'

curl --noproxy '*' -X POST "$BASE_URL/api/material?Action=ListAssets&Version=2024-01-01" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "PageNumber": 1,
    "PageSize": 10,
    "Filter": {
      "GroupIds": ["group-20260623180314-r2rc7"],
      "AssetType": "Image",
      "Statuses": ["Active"]
    }
  }'

curl --noproxy '*' -X POST "$BASE_URL/api/material?Action=UpdateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Id": "asset-20260623180317-8sxkd",
    "Name": "updated-person-reference"
  }'

curl --noproxy '*' -X POST "$BASE_URL/api/material?Action=DeleteAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Id":"asset-20260623180317-8sxkd"}'

{
  "type": "image_url",
  "image_url": {"url": "asset://asset-20260623180317-8sxkd"},
  "role": "reference_image"
}

curl --noproxy '*' -X POST "$BASE_URL/api/material?Action=CreateVisualValidateSession&Version=2024-01-01" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl --noproxy '*' -X POST "$BASE_URL/api/material?Action=GetVisualValidateResult&Version=2024-01-01" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"validate-token-xxxx"}'

curl --noproxy '*' -X POST "$BASE_URL/api/material?Action=CreateRealValidateH5&Version=2024-01-01" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v3/contents/generations/tasks

curl --noproxy '*' -X POST "$BASE_URL/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type":"text","text":"A natural, cinematic running shot with stable camera; no subtitles or watermark"},
      {
        "type":"image_url",
        "image_url":{"url":"asset://asset-20260623180317-8sxkd"},
        "role":"reference_image"
      }
    ],
    "resolution":"480p",
    "ratio":"16:9",
    "duration":4,
    "watermark":false
  }'

{
  "id": "cgt-20260731120000-example",
  "status": "queued",
  "model": "doubao-seedance-2-0-260128",
  "created_at": 1782208997
}

[
  {"type":"text","text":"Have the person run from the left side of the frame to the right"},
  {"type":"image_url","role":"first_frame","image_url":{"url":"YOUR_PUBLIC_FIRST_FRAME_URL"}},
  {"type":"image_url","role":"last_frame","image_url":{"url":"YOUR_PUBLIC_LAST_FRAME_URL"}},
  {"type":"video_url","role":"reference_video","video_url":{"url":"YOUR_PUBLIC_REFERENCE_VIDEO_URL"}}
]

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type":"image_url","role":"reference_image","image_url":{"url":"asset://asset-xxxx"}},
    {"type":"audio_url","role":"reference_audio","audio_url":{"url":"YOUR_PUBLIC_REFERENCE_AUDIO_URL"}}
  ],
  "resolution":"480p",
  "ratio":"16:9",
  "duration":4,
  "generate_audio":true
}

GET /api/v3/contents/generations/tasks/{task_id}

curl --noproxy '*' "$BASE_URL/api/v3/contents/generations/tasks/cgt-20260731120000-example" \
  -H "Authorization: Bearer $TOS_API_KEY"

{
  "id": "cgt-20260731120000-example",
  "status": "succeeded",
  "model": "doubao-seedance-2-0-260128",
  "content": {
    "video_url": "GENERATED_VIDEO_URL",
    "last_frame_url": "GENERATED_LAST_FRAME_URL"
  },
  "usage": {"completion_tokens": 100858},
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 4
}

curl --noproxy '*' -L "$VIDEO_URL" -o output.mp4

{
  "ResponseMetadata": {
    "RequestId": "2026062317822087486485654725234569",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Error": {"Code":"InvalidAction","Message":"unsupported Action"}
  }
}

{
  "error": {
    "code": "missing_model",
    "message": "model is required"
  }
}

pip install requests
export TOS_API_KEY="gk_YOUR_KEY"
export PERSON_IMAGE_URL="YOUR_PUBLIC_IMAGE_URL"

import os
import time

import requests


BASE_URL = os.getenv("TOS_BASE_URL", "https://ai.tos.run")
API_KEY = os.environ["TOS_API_KEY"]
MODEL = os.getenv("TOS_VIDEO_MODEL", "doubao-seedance-2-0-260128")
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def material(action, payload=None):
    response = requests.post(
        f"{BASE_URL}/api/material",
        params={"Action": action, "Version": "2024-01-01"},
        headers=HEADERS,
        json=payload or {},
        timeout=30,
    )
    response.raise_for_status()
    body = response.json()
    result = body.get("Result") or {}
    error = result.get("Error") or {}
    if error.get("Code") or error.get("Message"):
        raise RuntimeError(f"{action} failed: {error}")
    return result


def create_video(payload):
    response = requests.post(
        f"{BASE_URL}/api/v3/contents/generations/tasks",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()


def get_video(task_id):
    response = requests.get(
        f"{BASE_URL}/api/v3/contents/generations/tasks/{task_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()


def wait_for_asset(asset_id, timeout=600):
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        asset = material("GetAsset", {"Id": asset_id})
        if asset.get("Status") == "Active":
            return asset
        if asset.get("Status") == "Failed":
            raise RuntimeError(asset.get("Error"))
        time.sleep(5)
    raise TimeoutError(f"asset polling timed out: {asset_id}")


def wait_for_video(task_id, timeout=600):
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        task = get_video(task_id)
        if task.get("status") == "succeeded":
            return task
        if task.get("status") == "failed":
            raise RuntimeError(task.get("error"))
        time.sleep(5)
    raise TimeoutError(f"video polling timed out: {task_id}")


def main():
    group = material("CreateAssetGroup", {
        "Name": "person-references",
        "Description": "created by Python example",
    })
    asset = material("CreateAsset", {
        "GroupId": group["Id"],
        "Name": "person-reference",
        "AssetType": "Image",
        "URL": os.environ["PERSON_IMAGE_URL"],
    })
    wait_for_asset(asset["Id"])

    task = create_video({
        "model": MODEL,
        "content": [
            {"type": "text", "text": "A stable running shot in natural light; no subtitles"},
            {
                "type": "image_url",
                "image_url": {"url": f"asset://{asset['Id']}"},
                "role": "reference_image",
            },
        ],
        "resolution": "480p",
        "ratio": "16:9",
        "duration": 4,
        "watermark": False,
    })
    completed = wait_for_video(task["id"])
    print((completed.get("content") or {}).get("video_url"))


if __name__ == "__main__":
    main()

export TOS_API_KEY="gk_YOUR_KEY"
export PERSON_IMAGE_URL="YOUR_PUBLIC_IMAGE_URL"

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "strings"
    "time"
)

const model = "doubao-seedance-2-0-260128"

type Client struct { BaseURL, APIKey string; HTTPClient *http.Client }
type materialEnvelope struct { Result json.RawMessage `json:"Result"` }
type materialError struct { Code string `json:"Code"`; Message string `json:"Message"` }
type idResult struct { ID string `json:"Id"`; Status string `json:"Status"` }
type assetResult struct { Status string `json:"Status"` }
type videoTask struct { ID string `json:"id"`; Status string `json:"status"`; Content *videoContent `json:"content"` }
type videoContent struct { VideoURL string `json:"video_url"` }

func NewClient(baseURL, apiKey string) *Client {
    return &Client{BaseURL: strings.TrimRight(baseURL, "/"), APIKey: apiKey, HTTPClient: &http.Client{Timeout: 30 * time.Second}}
}

func (c *Client) doJSON(ctx context.Context, method, endpoint string, payload, result any) error {
    var body io.Reader
    if payload != nil {
        data, err := json.Marshal(payload); if err != nil { return fmt.Errorf("marshal request: %w", err) }
        body = bytes.NewReader(data)
    }
    request, err := http.NewRequestWithContext(ctx, method, endpoint, body)
    if err != nil { return fmt.Errorf("create request: %w", err) }
    request.Header.Set("Authorization", "Bearer "+c.APIKey)
    if payload != nil { request.Header.Set("Content-Type", "application/json") }
    response, err := c.HTTPClient.Do(request); if err != nil { return fmt.Errorf("send request: %w", err) }
    defer response.Body.Close()
    responseBody, err := io.ReadAll(io.LimitReader(response.Body, 8<<20)); if err != nil { return err }
    if response.StatusCode < 200 || response.StatusCode >= 300 { return fmt.Errorf("HTTP %d: %s", response.StatusCode, strings.TrimSpace(string(responseBody))) }
    if result == nil || len(bytes.TrimSpace(responseBody)) == 0 { return nil }
    return json.Unmarshal(responseBody, result)
}

func (c *Client) Material(ctx context.Context, action string, payload, result any) error {
    endpoint, err := url.Parse(c.BaseURL + "/api/material"); if err != nil { return err }
    query := endpoint.Query(); query.Set("Action", action); query.Set("Version", "2024-01-01"); endpoint.RawQuery = query.Encode()
    if payload == nil { payload = map[string]any{} }
    var envelope materialEnvelope
    if err := c.doJSON(ctx, http.MethodPost, endpoint.String(), payload, &envelope); err != nil { return err }
    var errorResult struct { Error *materialError `json:"Error"` }
    if err := json.Unmarshal(envelope.Result, &errorResult); err != nil { return err }
    if errorResult.Error != nil && (errorResult.Error.Code != "" || errorResult.Error.Message != "") { return fmt.Errorf("%s failed: %s", action, errorResult.Error.Message) }
    if result == nil { return nil }
    return json.Unmarshal(envelope.Result, result)
}

func (c *Client) CreateVideoTask(ctx context.Context, payload any) (videoTask, error) { var task videoTask; err := c.doJSON(ctx, http.MethodPost, c.BaseURL+"/api/v3/contents/generations/tasks", payload, &task); return task, err }
func (c *Client) GetVideoTask(ctx context.Context, taskID string) (videoTask, error) { var task videoTask; err := c.doJSON(ctx, http.MethodGet, c.BaseURL+"/api/v3/contents/generations/tasks/"+url.PathEscape(taskID), nil, &task); return task, err }

func waitForAsset(ctx context.Context, c *Client, assetID string, timeout time.Duration) error {
    deadline := time.Now().Add(timeout)
    for time.Now().Before(deadline) {
        var asset assetResult; if err := c.Material(ctx, "GetAsset", map[string]any{"Id": assetID}, &asset); err != nil { return err }
        if asset.Status == "Active" { return nil }; if asset.Status == "Failed" { return fmt.Errorf("asset failed: %s", assetID) }
        select { case <-ctx.Done(): return ctx.Err(); case <-time.After(5 * time.Second): }
    }
    return fmt.Errorf("asset polling timed out: %s", assetID)
}

func waitForVideo(ctx context.Context, c *Client, taskID string, timeout time.Duration) (videoTask, error) {
    deadline := time.Now().Add(timeout)
    for time.Now().Before(deadline) {
        task, err := c.GetVideoTask(ctx, taskID); if err != nil { return videoTask{}, err }
        if task.Status == "succeeded" { return task, nil }; if task.Status == "failed" { return videoTask{}, fmt.Errorf("video task failed: %s", taskID) }
        select { case <-ctx.Done(): return videoTask{}, ctx.Err(); case <-time.After(5 * time.Second): }
    }
    return videoTask{}, fmt.Errorf("video polling timed out: %s", taskID)
}

func run(ctx context.Context) error {
    apiKey, imageURL := strings.TrimSpace(os.Getenv("TOS_API_KEY")), strings.TrimSpace(os.Getenv("PERSON_IMAGE_URL"))
    if apiKey == "" || imageURL == "" { return fmt.Errorf("TOS_API_KEY and PERSON_IMAGE_URL are required") }
    c := NewClient("https://ai.tos.run", apiKey)
    var group idResult; if err := c.Material(ctx, "CreateAssetGroup", map[string]any{"Name": "person-references"}, &group); err != nil { return err }
    var asset idResult; if err := c.Material(ctx, "CreateAsset", map[string]any{"GroupId": group.ID, "Name": "person-reference", "AssetType": "Image", "URL": imageURL}, &asset); err != nil { return err }
    if err := waitForAsset(ctx, c, asset.ID, 10*time.Minute); err != nil { return err }
    task, err := c.CreateVideoTask(ctx, map[string]any{"model": model, "content": []any{
        map[string]any{"type": "text", "text": "A stable running shot in natural light; no subtitles"},
        map[string]any{"type": "image_url", "image_url": map[string]any{"url": "asset://" + asset.ID}, "role": "reference_image"},
    }, "resolution": "480p", "ratio": "16:9", "duration": 4, "watermark": false})
    if err != nil { return err }; completed, err := waitForVideo(ctx, c, task.ID, 10*time.Minute); if err != nil { return err }
    if completed.Content == nil { return fmt.Errorf("video task succeeded without content") }; fmt.Println(completed.Content.VideoURL); return nil
}

func main() { if err := run(context.Background()); err != nil { fmt.Fprintln(os.Stderr, err); os.Exit(1) } }