> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gregapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# BytePlus Dreamina Seedance 2.0

Call the overseas BytePlus Dreamina Seedance 2.0 model through GregAPI, covering video generation, video editing, video extension, and the asset library workflow. Task creation, querying, and asset library request fields follow the BytePlus native shape as closely as possible.

<Info>
  This page only covers the **overseas BytePlus Dreamina Seedance 2.0**. The domestic [Doubao Seedance 2.0](/en/api-reference/videos/seedance2) uses separate models, pricing, and asset capabilities.
</Info>

When you need to use real-person imagery, video, or audio that has been verified by the person themselves, first complete overseas H5 verification and asset ingestion through the [Real-Person Asset Library API](/en/api-reference/videos/real-person-assets), then create tasks with `asset://<AssetId>`.

## Endpoint

**POST** `https://api.gregapi.com/volcark/api/v3/contents/generations/tasks`

The overseas entry point is the BytePlus native task API. Task listing, cancellation/deletion, and asset library access are restricted to the current GregAPI tenant scope.

| Feature | Method & path |
| - | - |
| Create task | `POST /volcark/api/v3/contents/generations/tasks` |
| Query task | `GET /volcark/api/v3/contents/generations/tasks/{task_id}` |
| List tenant tasks | `GET /volcark/api/v3/contents/generations/tasks` |
| Cancel or delete task | `DELETE /volcark/api/v3/contents/generations/tasks/{task_id}` |

## Authentication

Authenticate with your API key by adding `Authorization: Bearer $GRAPAPI_API_KEY` to the request header. Callers only need the API token issued by GregAPI; the BytePlus API key, AK/SK, project name, and endpoint are all hosted by the platform.

| Header | Description |
| - | - |
| `Authorization` | `Bearer <API_KEY>` — the API token issued by GregAPI |
| `Content-Type` | `application/json` |

## Models

| External model | BytePlus official model | Description |
| - | - | - |
| `dreamina-seedance-2-0` | `dreamina-seedance-2-0-260128` | Overseas standard model; supports `480p` / `720p` / `1080p` / `4k` |
| `dreamina-seedance-2-0-fast` | `dreamina-seedance-2-0-fast-260128` | Overseas fast model; supports only `480p` / `720p` |
| `dreamina-seedance-2-0-mini` | `dreamina-seedance-2-0-mini-260615` | Overseas Mini model; supports only `480p` / `720p` |
| `dreamina-seedance-2-0-filter-off` | BytePlus Filter-Off model | Overseas standard Filter-Off model; same pricing and capabilities as `dreamina-seedance-2-0` |
| `dreamina-seedance-2-0-fast-filter-off` | BytePlus Filter-Off model | Overseas fast Filter-Off model; same pricing and capabilities as `dreamina-seedance-2-0-fast` |

For the `model` field, use the stable external model name on the left. For BytePlus official version compatibility, the platform also accepts the following official version names and normalizes them to the stable external model name in task queries, task lists, asset library responses, and billing audits:

* `dreamina-seedance-2-0-260128` → `dreamina-seedance-2-0`
* `dreamina-seedance-2-0-fast-260128` → `dreamina-seedance-2-0-fast`
* `dreamina-seedance-2-0-mini-260615` → `dreamina-seedance-2-0-mini`

`seedance-2-0`, `seedance-2-0-260128`, `seedance-2-0-fast`, `seedance-2-0-fast-260128`, `seedance-2-0-mini`, and `dreamina-seedance-2.0-mini` are console or resource-page short IDs and are not accepted as the external `model` parameter. `dreamina-seedance-2-0-filter-off-260128`, `dreamina-seedance-2-0-260128-filter-off`, `dreamina-seedance-2-0-fast-filter-off-260128`, and `dreamina-seedance-2-0-fast-260128-filter-off` are not official BytePlus model names, and the platform does not map them. In query and list responses the `model` field echoes the GregAPI external model from the creation request to avoid exposing service configuration, billing details, or implementation specifics.

### 4K capability

The overseas standard model supports 4K: set `resolution` to `4k`; output is **10-bit / H.265**. The fast and mini models do not support `1080p` or `4k` and must fall back to `480p` / `720p`.

| ratio | 4K size |
| - | - |
| `16:9` | `3840x2160` |
| `9:16` | `2160x3840` |
| `1:1` | `2880x2880` |
| `4:3` | `3326x2494` |
| `3:4` | `2494x3326` |
| `21:9` | `4398x1886` |

## Overseas pricing

Only successfully rendered tasks are settled; failed tasks are not billed as successful renders.

| SKU | Price |
| - | - |
| `dreamina-seedance-2-0-480p-novideo` | \$7.0/M tokens |
| `dreamina-seedance-2-0-480p-video` | \$4.3/M tokens |
| `dreamina-seedance-2-0-720p-novideo` | \$7.0/M tokens |
| `dreamina-seedance-2-0-720p-video` | \$4.3/M tokens |
| `dreamina-seedance-2-0-1080p-novideo` | \$7.7/M tokens |
| `dreamina-seedance-2-0-1080p-video` | \$4.7/M tokens |
| `dreamina-seedance-2-0-4k-novideo` | \$4.0/M tokens |
| `dreamina-seedance-2-0-4k-video` | \$2.4/M tokens |
| `dreamina-seedance-2-0-fast-novideo` | \$5.6/M tokens |
| `dreamina-seedance-2-0-fast-video` | \$3.3/M tokens |
| `dreamina-seedance-2-0-mini-novideo` | \$3.5/M tokens |
| `dreamina-seedance-2-0-mini-video` | \$2.1/M tokens |

`video` means the request includes a video reference input; `novideo` means it does not. `dreamina-seedance-2-0-filter-off` reuses all SKUs of `dreamina-seedance-2-0`; `dreamina-seedance-2-0-fast-filter-off` reuses all SKUs of `dreamina-seedance-2-0-fast`. Logs and task audits keep the Filter-Off external model name from the creation request.

## Request parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `model` | string | Yes | Model ID, e.g. `dreamina-seedance-2-0`. |
| `content` | array | Yes | BytePlus multimodal input array; at least a prompt text or reference asset. |
| `duration` | integer | Yes | Video duration in seconds, `4-15`; pass `-1` to let the model service auto-select. |
| `ratio` | string | No | Aspect ratio: `adaptive`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`. |
| `resolution` | string | No | `480p`, `720p`, `1080p`, `4k`; 4K only for the standard model. |
| `generate_audio` | boolean | No | Whether to generate audio. |
| `watermark` | boolean | No | Whether to keep the watermark. |
| `return_last_frame` | boolean | No | Return `content.last_frame_url` on success. |
| `execution_expires_after` | integer | No | Task execution expiry in seconds; official range is typically `3600-259200`. |
| `priority` | integer | No | Queue priority `0-9`. |
| `safety_identifier` | string | No | Stable end-user identifier; pass a hashed user ID. |
| `callback_url` | string | No | BytePlus native task status callback URL; must be a non-empty public HTTPS URL. |
| `CallbackURL` | string | No | Compatibility alias; normalized to `callback_url` before submitting to the model service. |

<Info>
  The overseas Mini supports only `480p` / `720p` and supports audio reference input. `references.audio` or native `content[].type=audio_url` is passed through as ordinary reference audio; `service_tier=flex` and `draft=true` are still rejected before calling BytePlus. The overseas Mini is delivered in the BytePlus AP region by default; the EU region must be probed before being opened.
</Info>

## Create a task

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.gregapi.com/volcark/api/v3/contents/generations/tasks" \
    -H "Authorization: Bearer $GRAPAPI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "dreamina-seedance-2-0",
      "content": [
        {
          "type": "text",
          "text": "A quiet cinematic shot of a paper boat floating on calm water, soft morning light."
        }
      ],
      "duration": 4,
      "ratio": "16:9",
      "resolution": "4k",
      "generate_audio": false,
      "watermark": true,
      "return_last_frame": true,
      "execution_expires_after": 3600,
      "priority": 0,
      "safety_identifier": "user-hash-001",
      "callback_url": "https://example.com/volcark/callback"
    }'
  ```

  ```python Python theme={null}
  import requests

  headers = {
      "Authorization": "Bearer $GRAPAPI_API_KEY",
      "Content-Type": "application/json",
  }

  data = {
      "model": "dreamina-seedance-2-0",
      "content": [
          {"type": "text", "text": "A quiet cinematic shot of a paper boat floating on calm water, soft morning light."}
      ],
      "duration": 4,
      "ratio": "16:9",
      "resolution": "4k",
      "generate_audio": False,
      "watermark": True,
      "return_last_frame": True,
      "execution_expires_after": 3600,
      "priority": 0,
      "safety_identifier": "user-hash-001",
      "callback_url": "https://example.com/volcark/callback",
  }

  resp = requests.post(
      "https://api.gregapi.com/volcark/api/v3/contents/generations/tasks",
      headers=headers,
      json=data,
  )
  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const resp = await fetch("https://api.gregapi.com/volcark/api/v3/contents/generations/tasks", {
    method: "POST",
    headers: {
      "Authorization": "Bearer $GRAPAPI_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "dreamina-seedance-2-0",
      content: [
        { type: "text", text: "A quiet cinematic shot of a paper boat floating on calm water, soft morning light." }
      ],
      duration: 4,
      ratio: "16:9",
      resolution: "4k",
      generate_audio: false,
      watermark: true,
      return_last_frame: true,
      execution_expires_after: 3600,
      priority: 0,
      safety_identifier: "user-hash-001",
      callback_url: "https://example.com/volcark/callback"
    }),
  });
  console.log(await resp.json());
  ```
</CodeGroup>

A Filter-Off call only replaces `model`; other request fields stay the same as the ordinary overseas Dreamina 2.0:

```json Filter-Off request theme={null}
{
  "model": "dreamina-seedance-2-0-filter-off",
  "content": [
    {
      "type": "text",
      "text": "A cinematic product shot with clean studio lighting."
    }
  ],
  "duration": 4,
  "ratio": "16:9",
  "resolution": "720p"
}
```

```json Success response theme={null}
{ "id": "cgt-20260611204121-462cw" }
```

<Info>
  Task creation is asynchronous; a successful response only returns the task ID. Query the task to retrieve the final video result. The GregAPI native response does not append `platform_id` by default, preserving the BytePlus native response shape.
</Info>

## Query a task

**GET** `https://api.gregapi.com/volcark/api/v3/contents/generations/tasks/{task_id}`

```bash cURL theme={null}
curl "https://api.gregapi.com/volcark/api/v3/contents/generations/tasks/cgt-20260611204121-462cw" \
  -H "Authorization: Bearer $GRAPAPI_API_KEY"
```

```json Success response theme={null}
{
  "id": "cgt-20260611204121-462cw",
  "model": "dreamina-seedance-2-0",
  "status": "succeeded",
  "content": {
    "video_url": "https://...",
    "last_frame_url": "https://..."
  },
  "usage": {
    "completion_tokens": 40594,
    "total_tokens": 40594
  },
  "created_at": 1781181681,
  "updated_at": 1781181802,
  "seed": 74719,
  "resolution": "4k",
  "ratio": "16:9",
  "duration": 4,
  "framespersecond": 24,
  "service_tier": "default",
  "execution_expires_after": 3600,
  "generate_audio": false,
  "draft": false,
  "safety_identifier": "user-hash-001",
  "priority": 0
}
```

Common statuses: `queued`, `running`, `succeeded`, `failed`, `expired`, `cancelled`. Result URLs are usually valid for about 24 hours; save them promptly. If `return_last_frame=true` was requested, the success result may include `content.last_frame_url`.

## List tenant tasks

**GET** `https://api.gregapi.com/volcark/api/v3/contents/generations/tasks`

```bash cURL theme={null}
curl "https://api.gregapi.com/volcark/api/v3/contents/generations/tasks?page_num=1&page_size=20&filter.status=succeeded&filter.model=dreamina-seedance-2-0" \
  -H "Authorization: Bearer $GRAPAPI_API_KEY"
```

```json Response example theme={null}
{
  "items": [
    {
      "id": "cgt-20260611204121-462cw",
      "status": "succeeded",
      "model": "dreamina-seedance-2-0",
      "execution_expires_after": 3600,
      "service_tier": "default",
      "safety_identifier": "user-hash-001"
    }
  ],
  "total": 1
}
```

| Parameter | Description |
| - | - |
| `page_num` | Page number, starting from `1` |
| `page_size` | Items per page |
| `filter.status` | `queued`, `running`, `succeeded`, `failed`, `expired`, `cancelled` |
| `filter.model` | The GregAPI external model from the creation request |
| `filter.task_ids` | Comma-separated BytePlus native task IDs |

The list endpoint is the BytePlus-compatible list within the current GregAPI tenant scope and does not return other tenants' or account-level full task lists.

## Cancel or delete a task

**DELETE** `https://api.gregapi.com/volcark/api/v3/contents/generations/tasks/{task_id}`

```bash cURL theme={null}
curl -X DELETE "https://api.gregapi.com/volcark/api/v3/contents/generations/tasks/cgt-20260611204121-462cw" \
  -H "Authorization: Bearer $GRAPAPI_API_KEY"
```

A running task may return `409`:

```json 409 response theme={null}
{
  "error": {
    "code": "InvalidAction.RunningTaskDeletion",
    "message": "Cannot delete task because it is currently running.",
    "param": "",
    "type": "Conflict"
  }
}
```

GregAPI keeps local task audit and billing records. For tasks that do not support in-flight deletion, deleting a terminal task hides it locally within the GregAPI tenant, while a running task returns `409`. You can only delete or cancel tasks that belong to the current tenant.

## Video editing and extension

Video generation, editing, and extension are all expressed through the same creation endpoint. Pass the video, reference image, or reference audio to edit or extend via `content[]`, and describe the target result with a text prompt.

| Scenario | Recommended input |
| - | - |
| Video editing | `text` + `video_url` (`role=reference_video`), optional `image_url.role=reference_image` / `audio_url.role=reference_audio` |
| Extend forward or backward | `text` + 1 `video_url` (`role=reference_video`), state the direction in the prompt |
| Join multiple clips | `text` + 2-3 `video_url` (`role=reference_video`) |
| Strict first or last frame | `image_url` (`role=first_frame` / `last_frame`) |

GregAPI requires you to first upload images, videos, or audio through the asset library and wait until the asset becomes `Active` before passing it as `asset://<Asset_Id>`. Tasks that include `content[].type=video_url` are billed under the video-reference-input SKU; tasks without `video_url` do not enter the `*-video` SKU.

```bash Video editing theme={null}
curl -X POST "https://api.gregapi.com/volcark/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $GRAPAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [
      {
        "type": "text",
        "text": "Edit Video 1: replace the red mug with a glass teapot while preserving the original camera movement."
      },
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": { "url": "asset://asset-20260611210200-video1" }
      },
      {
        "type": "image_url",
        "role": "reference_image",
        "image_url": { "url": "asset://asset-20260611210100-image1" }
      }
    ],
    "duration": 6,
    "ratio": "16:9",
    "resolution": "720p",
    "generate_audio": false
  }'
```

```bash Video extension theme={null}
curl -X POST "https://api.gregapi.com/volcark/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $GRAPAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [
      {
        "type": "text",
        "text": "Extend Video 1 backward with the same character, lighting, and handheld camera motion, then end with Video 1."
      },
      {
        "type": "video_url",
        "role": "reference_video",
        "video_url": { "url": "asset://asset-20260611210200-video1" }
      }
    ],
    "duration": 6,
    "ratio": "16:9",
    "resolution": "720p",
    "generate_audio": false
  }'
```

## Native callback

`POST /volcark/api/v3/contents/generations/tasks` supports a top-level `callback_url`. The platform validates the URL before submitting the creation request to the model service. Validation rules:

* It must be a string and must not be empty after trimming whitespace.
* It must use `https`.
* The domain must resolve to a publicly routable address; local, private, link-local, multicast, and CGNAT addresses are rejected.
* On validation failure, the platform returns HTTP `400` with error code `invalid_request` before submitting to the model service.

The compatibility field `CallbackURL` is normalized to `callback_url`. If both are present, `callback_url` takes precedence. This is native task callback passthrough, not a GregAPI webhook broker; callback delivery, retry, signing, and payload structure all follow the model service's native capabilities.

## Asset library workflow

The asset library comes with the overseas Dreamina 2.0. Use it to: create asset groups, upload image/video/audio assets, save the `Result.Id` returned by `CreateAsset`, and query the asset lifecycle with `GetAsset` (only `Active` assets can enter generation tasks).

All Asset APIs are mounted at `POST /volcark/?Action={ActionName}&Version=2024-01-01`.

| Feature | Action |
| - | - |
| Create asset group | `CreateAssetGroup` |
| Create asset | `CreateAsset` |
| List asset groups | `ListAssetGroups` |
| List assets | `ListAssets` |
| Get a single asset group | `GetAssetGroup` |
| Get a single asset | `GetAsset` |

`Update*`, `Delete*`, and `Moderation.Strategy=Skip` are not enabled. On success, `CreateAssetGroup` and `CreateAsset` return only `Id` in `Result`; asset status, URL, moderation, or preprocessing failure reasons are not expanded in the Create response.

### Create asset group

```bash cURL theme={null}
curl -X POST "https://api.gregapi.com/volcark/?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $GRAPAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-fast",
    "Name": "campaign-product-shots",
    "GroupType": "AIGC",
    "Description": "Assets for product videos"
  }'
```

```json Success response theme={null}
{
  "ResponseMetadata": {
    "Action": "CreateAssetGroup",
    "Region": "ap-southeast-1",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": { "Id": "group-20260611210000-abcd1" }
}
```

### Create asset

```bash cURL theme={null}
curl -X POST "https://api.gregapi.com/volcark/?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $GRAPAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-fast",
    "GroupId": "group-20260611210000-abcd1",
    "URL": "https://example.com/product.png",
    "AssetType": "Image",
    "Name": "product-front.png"
  }'
```

* `AssetType` supports `Image`, `Video`, and `Audio`.
* Use the `URL` field; the platform also accepts `Url` / `url`.
* `Result.Id` is the stable asset ID used by subsequent `GetAsset` and `asset://<Result.Id>` calls.
* Asset URLs must be publicly downloadable and must not rely on cookies, login state, or one-time links.
* Only assets with `Status=Active` can be used for video generation.

```json Success response theme={null}
{
  "ResponseMetadata": {
    "Action": "CreateAsset",
    "Service": "ark",
    "Version": "2024-01-01"
  },
  "Result": { "Id": "asset-20260611210100-efgh2" }
}
```

### Query an asset

```bash cURL theme={null}
curl -X POST "https://api.gregapi.com/volcark/?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $GRAPAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-fast",
    "Id": "asset-20260611210100-efgh2"
  }'
```

Common statuses: `Processing`, `Active`, `Failed`. After `CreateAsset` returns `Result.Id`, use `GetAsset` to query the lifecycle; if the status is still `Processing`, poll `GetAsset` with backoff until it enters `Active` or `Failed`. On success, pass it as `asset://<Asset_Id>` in the generation task.

### List assets

```bash cURL theme={null}
curl -X POST "https://api.gregapi.com/volcark/?Action=ListAssets&Version=2024-01-01" \
  -H "Authorization: Bearer $GRAPAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-fast",
    "GroupId": "group-20260611210000-abcd1"
  }'
```

<Info>
  Only assets with `Status=Active` can be used for video generation. Asset URLs must be publicly downloadable. After `CreateAsset` returns `Result.Id`, poll `GetAsset` with backoff until the asset enters `Active` or `Failed`.
</Info>

## Multi-tenant boundary

Task listing, cancellation/deletion, and asset library access are all restricted to the current GregAPI tenant scope and do not return other tenants' or account-level full tasks and assets. Billing and permissions are based on the GregAPI external model from the creation request, the final resolution, and the reference input type.

## Error codes

| Status | Error type | Description |
| - | - | - |
| 400 | `invalid_request` | The request body is not valid JSON or is missing required fields. |
| 400 | `invalid_duration` | `duration` is outside the allowed range. |
| 403 | `InvalidAction` | An asset `Update*` / `Delete*` operation that is not enabled was requested. |
| 404 | `task_not_found` | The task does not exist or does not belong to the current tenant. |
| 404 | `ResourceNotFound.Asset` | The asset does not exist or does not belong to the current tenant. |
| 409 | `InvalidAction.RunningTaskDeletion` | A running task cannot be deleted. |
| 502 | `service_error` | The model service returned an error. |
| 503 | `service_unavailable` | The account has not yet enabled the overseas BytePlus Dreamina Seedance 2.0 or asset library capability. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.