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

# Seedance 官方镜像概览

> Seedance 官方镜像 API（与 BytePlus Ark 请求/响应完全一致）

## 简介

Seedance 官方镜像 API 与 BytePlus Ark Seedance 官方接口 **请求体、响应体完全一致**，只有 Base URL 和鉴权方式不同。已有官方 SDK 调用代码只需改 `base_url` 与 `Authorization` 即可接入。

**Base URL**：`https://api.gravitex.ai`

| 模型 ID               | 说明                               | 分辨率                             |
| ------------------- | -------------------------------- | ------------------------------- |
| `seedance-2-0`      | 标准版                              | `480p`、`720p`、`1080p`、`4K`      |
| `seedance-2-5`      | 新一代多模态模型，支持视频生成、视频编辑与视频延长        | 同 `seedance-2-0`                |
| `seedance-2-0-mini` | 高性价比版本，生成成本约为 `seedance-2-0` 的一半 | `480p`、`720p`（不支持 `1080p`/`4K`） |
| `seedance-2-0-fast` | 快速版                              | `480p`、`720p`（不支持 `1080p`/`4K`） |

<Note>
  这与平台通用接口（[`/v1/video/generations`](/cn/api-reference/endpoint/seedance-2.0/create-video-generation)、[`/v1/assets`](/cn/api-reference/endpoint/seedance-2.0/create-asset) 等）是另一套独立接口：素材库数据互通，视频任务路由互不干扰。
</Note>

## 认证

所有接口：`Authorization: Bearer sk-{your_token_key}`，`Content-Type: application/json`。

## 素材库类型

| 库类型   | `GroupType`    | 创建方式                                                                                                            |
| ----- | -------------- | --------------------------------------------------------------------------------------------------------------- |
| 虚拟素材库 | `AIGC`         | [CreateAssetGroup](/cn/api-reference/endpoint/seedance-2.0-new/create-asset-group)                              |
| 真人素材库 | `LivenessFace` | [CreateVisualValidateSession](/cn/api-reference/endpoint/seedance-2.0-new/create-visual-validate-session) H5 核验 |

推荐流程：创建素材组 → [CreateAsset](/cn/api-reference/endpoint/seedance-2.0-new/create-asset) → 轮询至 `Status: Active` → [创建任务](/cn/api-reference/endpoint/seedance-2.0-new/create-video-generation) → [查询任务](/cn/api-reference/endpoint/seedance-2.0-new/get-video-generation)。

## 接口目录

### 视频生成任务

<CardGroup cols={2}>
  <Card title="创建任务" icon="upload" href="/cn/api-reference/endpoint/seedance-2.0-new/create-video-generation">
    POST /api/v3/contents/generations/tasks
  </Card>

  <Card title="查询任务" icon="search" href="/cn/api-reference/endpoint/seedance-2.0-new/get-video-generation">
    GET /api/v3/contents/generations/tasks/{id}
  </Card>

  <Card title="取消/删除任务" icon="trash" href="/cn/api-reference/endpoint/seedance-2.0-new/delete-video-generation">
    DELETE /api/v3/contents/generations/tasks/{id}
  </Card>
</CardGroup>

### 素材库（统一信封 Action）

所有素材库操作走同一端点，用 `Action` 查询参数区分：

```
POST https://api.gravitex.ai/api/v3/seedance?Action=<Action名>&Version=2024-01-01
```

响应为 `{ ResponseMetadata, Result }` 信封（真人核验两个 Action 除外，为扁平结构）。

<CardGroup cols={2}>
  <Card title="CreateAssetGroup" icon="folder-plus" href="/cn/api-reference/endpoint/seedance-2.0-new/create-asset-group">
    创建素材组（强制 AIGC）
  </Card>

  <Card title="CreateAsset" icon="file-plus" href="/cn/api-reference/endpoint/seedance-2.0-new/create-asset">
    创建素材
  </Card>

  <Card title="ListAssetGroups" icon="folders" href="/cn/api-reference/endpoint/seedance-2.0-new/list-asset-groups">
    查询素材组列表
  </Card>

  <Card title="ListAssets" icon="list" href="/cn/api-reference/endpoint/seedance-2.0-new/list-assets">
    查询素材列表
  </Card>

  <Card title="GetAsset" icon="file" href="/cn/api-reference/endpoint/seedance-2.0-new/get-asset">
    查询单个素材
  </Card>

  <Card title="GetAssetGroup" icon="folder" href="/cn/api-reference/endpoint/seedance-2.0-new/get-asset-group">
    查询单个素材组
  </Card>

  <Card title="UpdateAsset" icon="pen" href="/cn/api-reference/endpoint/seedance-2.0-new/update-asset">
    更新素材（Name）
  </Card>

  <Card title="UpdateAssetGroup" icon="pen-to-square" href="/cn/api-reference/endpoint/seedance-2.0-new/update-asset-group">
    更新素材组（Name/Description）
  </Card>

  <Card title="DeleteAsset" icon="file-minus" href="/cn/api-reference/endpoint/seedance-2.0-new/delete-asset">
    删除素材
  </Card>

  <Card title="DeleteAssetGroup" icon="trash" href="/cn/api-reference/endpoint/seedance-2.0-new/delete-asset-group">
    删除素材组（级联）
  </Card>
</CardGroup>

### 真人素材库（LivenessFace）

<CardGroup cols={2}>
  <Card title="CreateVisualValidateSession" icon="user-check" href="/cn/api-reference/endpoint/seedance-2.0-new/create-visual-validate-session">
    发起真人核验会话
  </Card>

  <Card title="GetVisualValidateResult" icon="user" href="/cn/api-reference/endpoint/seedance-2.0-new/get-visual-validate-result">
    查询核验结果并创建素材组
  </Card>
</CardGroup>

## 推荐流程

1. （可选）CreateAssetGroup → CreateAsset → 轮询至 `Status: Active`
2. `POST /api/v3/contents/generations/tasks` 提交任务
3. `GET /api/v3/contents/generations/tasks/{id}` 轮询至 `succeeded`
4. 需要时可 `DELETE` 取消排队中任务或清理已完成记录

## 错误处理

素材库错误走信封 `ResponseMetadata.Error.{Code,Message}`：

| 场景              | HTTP  | `Error.Code`       |
| --------------- | ----- | ------------------ |
| `Action` 不在支持列表 | `400` | `InvalidAction`    |
| 请求体不是合法 JSON    | `400` | `InvalidParameter` |
| 无可用渠道           | `503` | `NoChannel`        |
| 配额检查服务端异常       | `500` | `QuotaCheckFailed` |
| 超出素材组数量上限       | `403` | `QuotaExceeded`    |
| 上游调用失败          | `502` | `UpstreamError`    |

视频生成任务 API 错误会返回相应的上游状态码和错误体。