第 1 课

开通 Seedance 2.5 并取得 API Key,用 SDK 和 curl 提交第一个文生视频任务

开通 Seedance 2.5 并取得 API Key,用 SDK 和 curl 提交第一个文生视频任务

图文22 分钟

课程目录第 1 / 3 课

学习位置仅保存在当前浏览器,有效期 180 天。

01 / 图文教材

开通 Seedance 2.5 并取得 API Key,用 SDK 和 curl 提交第一个文生视频任务

本课对照官方文档「Doubao Seedance 2.5 系列教程」「视频生成教程」「创建视频生成任务」「Seedance 模型开通、使用与退订说明」编写。命令在 2026-11-21 核对;成功成片采用官方文档示例,本环境未用真实密钥跑出成功视频。401 为同日用缺失 Key 和假 Key 实打。

本课目标

  • 认清本课要调用的 Model ID:doubao-seedance-2-5-flash-261115,并把它和旗舰 ID 分开
  • 按官方条件开通 Seedance 2.5 系列,在方舟创建 API Key,并导出环境变量
  • 安装官方 Python SDK,用官方文生视频示例提交第一个任务
  • 用官方创建接口的 curl 再提交一次,请求体仍用官方提示词
  • 用缺失 Key 和假 Key 复现 401 AuthenticationError,确认请求打到了官方接口

前置条件

  • 已有火山引擎账号
  • 本机有 curl,以及 Python 3
  • 会在终端里设置环境变量
  • 已按官方开通说明准备好账户余额或资源包。开通 Seedance 2.5 系列需要满足官方给出的门槛,详见下文。课程阅读免费,跟做调用会产生费用。

第 1 步:先认清要调用的模型

本课只调用 Seedance 2.5 Flash,不要写成旗舰。官方系列教程「能力概述」对照表给出的 Model ID 是:

模型Model ID
Seedance 2.5(旗舰)doubao-seedance-2-5-260628
Seedance 2.5 flashdoubao-seedance-2-5-flash-261115

官方示例代码里常常写 doubao-seedance-2-5-260628,旁边注释是 Replace with Model ID。那是旗舰 ID。本课抄代码时一律改成 doubao-seedance-2-5-flash-261115,其余字段保持官方原样。版本号 261115 对应主版本,不是模型首发日:模型发布于 2026 年 11 月 12 日,方舟 API 上线于 2026 年 11 月 15 日。

Flash 与旗舰的完整差异放到第 3 课。这里先记住两件和第一次调用直接相关的事:Flash 分辨率只支持 480p、720p(8bit),官方默认分辨率是 720p;不要把 resolution 写成 1080p 或 4k。官方文生视频示例没有显式传 resolution,会走默认值 720p,这对 Flash 是合法取值。

官方系列教程「能力概述」对照表中的 Model ID

2026-11-21 用无头 Chrome 对系列教程实拍,已滚动到「能力概述」。表中可见旗舰 ID doubao-seedance-2-5-260628 与 Flash ID doubao-seedance-2-5-flash-261115。

https://ark.volcengine.com/region:cn-beijing/docs/seedance-2-5

官方「Doubao Seedance 2.5 系列教程」页首,含模型开通条件

2026-11-21 用无头 Chrome 对下面这个地址实拍,视口 1280×800。图中「模型开通条件」写的是账户余额大于 200 元;专用开通说明的门槛表述是「账户可用余额达到 200 元」,本课以开通说明为准,见下一步。

https://ark.volcengine.com/region:cn-beijing/docs/seedance-2-5

第 2 步:开通模型,创建 API Key,并导出环境变量

跟做之前,先按官方开通说明满足门槛。满足以下任意一项,即可开通 Seedance 2.5 系列与 Seedance 2.0 系列模型:

  • 账户可用余额达到 200 元
  • 购买 200 元及以上规格的专属递减型节省计划,且当前有余额
  • 购买 200 元及以上的 Seedance 2.0 或 2.5 系列任一模型资源包,且当前有余量

开通说明还写明:前往开通管理开通对应模型,再前往 API Key 管理获取 API Key,发起在线推理请求。系列教程「新手入门」也写到:账户余额大于等于 200 元,或已购买资源包,否则无法开通。

按官方步骤操作:

  1. 使用火山引擎账号登录。
  2. 到开通管理开通 Seedance 2.5 flash。
  3. 到 API Key 管理页,点击「创建 API Key」,复制并妥善保存。不要把真实 Key 写进代码、笔记本或聊天记录。

官方开通说明「满足开通门槛」

2026-11-21 实拍。表中门槛条件写的是「账户可用余额达到 200 元」,以及 200 元及以上节省计划或资源包。

https://ark.volcengine.com/region:cn-beijing/docs/seedance-model-activation-usage-and-refund

创建成功后,在当前终端会话里导出环境变量。官方示例使用的变量名是 ARK_API_KEY:

export ARK_API_KEY="YOUR_API_KEY"

若只想确认变量在,可以打印前几位:

echo "Key 前缀:${ARK_API_KEY:0:7}********"

第 3 步:安装官方 Python SDK,提交第一条文生视频任务

官方安装命令是:

python -m pip install --upgrade arkruntime

下面就是官方「视频生成教程」文生视频一节的 Python 示例。原文把 model 写成 doubao-seedance-2-5-260628,并注释 Replace with Model ID。这里只把 Model ID 换成 Flash,提示词、ratio、duration、watermark 以及轮询逻辑都与官方原文一致,未改任何字:

import os
import time
# Install SDK:  python -m pip install --upgrade arkruntime
from arkruntime import Ark

# Make sure that you have stored the API Key in the environment variable ARK_API_KEY
# Initialize the Ark client to read your API Key from an environment variable
client = Ark(
    # This is the default path. You can configure it based on the service location
    base_url="https://ark.cn-beijing.volces.com/api/v3",
    # Get API Key:https://ark.volcengine.com/region:cn-beijing/apikey
    api_key=os.environ.get("ARK_API_KEY"),
)

if __name__ == "__main__":
    print("----- create request -----")
    create_result = client.content_generation.tasks.create(
        model="doubao-seedance-2-5-flash-261115",  # 官方示例写的是旗舰 ID,已按注释换成 Flash
        content=[
            {
                # Combination of text prompt and parameters
                "type": "text",
                "text": "写实风格,晴朗的蓝天之下,一大片白色的雏菊花田,镜头逐渐拉近,最终定格在一朵雏菊花的特写上,花瓣上有几颗晶莹的露珠"
            }
        ],
        ratio="16:9",
        duration=5,
        watermark=True,
    )
    print(create_result)

    # Polling query section
    print("----- polling task status -----")
    task_id = create_result.id
    while True:
        get_result = client.content_generation.tasks.get(task_id=task_id)
        status = get_result.status
        if status == "succeeded":
            print("----- task succeeded -----")
            print(get_result)
            break
        elif status == "failed":
            print("----- task failed -----")
            print(f"Error: {get_result.error}")
            break
        else:
            print(f"Current status: {status}, Retrying after 10 seconds...")
            time.sleep(10)

把这段保存为 t2v_flash.py,然后运行:

python t2v_flash.py

这是一次计费调用。创建接口是异步的:成功提交后先拿到任务 ID,再通过 client.content_generation.tasks.get 轮询。官方示例每隔 10 秒查询一次,直到 succeeded 或 failed。下一课会把成功和失败返回拆开看。

官方文档在同一条提示词旁给出了效果预览视频,这是文档里的示例成片,不是本机跑出来的:

https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/b847f3e831c244b39f7b4d53d904988f

官方「视频生成教程」文生视频示例:雏菊花田提示词、预览成片与 Python 代码

2026-11-21 实拍,已滚动到官方文生视频示例。页上当时有文档站引导浮层,提示词、预览视频和 SDK 示例仍可见。

https://ark.volcengine.com/region:cn-beijing/docs/video-generation-tutorial

第 4 步:用官方 curl 再提交一次

官方「创建视频生成任务」页给出的路径和请求头是:POST 到 /api/v3/contents/generations/tasks,使用 Authorization: Bearer $ARK_API_KEY。该页的 curl 示例请求体是全模态参考任务。下面这条 curl 只把请求体换成上一节官方文生视频示例的字段,并把 Model ID 换成 Flash,路径和请求头保持官方原样:

curl -X POST \
  "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-5-flash-261115",
    "content": [
      {
        "type": "text",
        "text": "写实风格,晴朗的蓝天之下,一大片白色的雏菊花田,镜头逐渐拉近,最终定格在一朵雏菊花的特写上,花瓣上有几颗晶莹的露珠"
      }
    ],
    "ratio": "16:9",
    "duration": 5,
    "watermark": true
  }'

完整接口地址单独占一行,避免横向溢出:

https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks

创建成功后,官方 Python 示例打印的是类似下面的任务 ID(这是官方「创建视频生成任务」页的示例输出,其中后续查询结果里的 model 写的是旗舰 ID;你用 Flash 调用时,这个字段会是 doubao-seedance-2-5-flash-261115):

----- create request -----
ContentGenerationTaskID(id='cgt-20260414114820-*****')

拿到 id 之后不要关闭终端,下一课要用它查询成片。视频生成需要等待,官方示例在 running 等状态上会每隔 10 秒重试。

官方「创建视频生成任务」页首屏,可见 POST 路径与 Python SDK 示例

2026-11-21 实拍。右侧示例里的 model 仍是官方原文的旗舰 ID doubao-seedance-2-5-260628,请按注释换成 Flash。页上当时有文档站引导浮层。

https://ark.volcengine.com/region:cn-beijing/docs/create-video-generation-task-api

第 5 步:用缺失 Key 和假 Key 复现 401

在确认地址和请求体无误后,可以先不带真实密钥看报错长什么样。下面两次请求都不要使用你的真 Key。

先完全不带 Authorization 头:

curl -sS -D - -X POST \
  "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-flash-261115",
    "content": [
      {"type": "text", "text": "ping"}
    ],
    "ratio": "16:9",
    "duration": 5,
    "watermark": true
  }'

2026-11-21 00:04(Australia/Perth,与 Asia/Shanghai 同时区)在本课用上述请求实打,HTTP 状态码为 401,响应头 x-error-code 为 AuthN_MissOrInvalidAuthorizationHeader。响应正文如下:

{
  "error": {
    "code": "AuthenticationError",
    "message": "the API key or AK/SK in the request is missing or invalid. request id: 021795190642843fc70b79e699e1a6fcafbbefdc4fb04128136c6",
    "param": "",
    "type": "Unauthorized"
  }
}

再用一把明显无效的假 Key,带上官方要求的 Bearer 头:

export ARK_API_KEY="ark-test-invalid-key-kun-course"
curl -sS -D - -X POST \
  "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-5-flash-261115",
    "content": [
      {"type": "text", "text": "ping"}
    ],
    "ratio": "16:9",
    "duration": 5,
    "watermark": true
  }'

同日实打,HTTP 状态码仍为 401,响应头 x-error-code 为 AuthN_AuthenticationError。响应正文如下:

{
  "error": {
    "code": "AuthenticationError",
    "message": "The API key format is incorrect. Request id: 02179519064686488db556329240132465f0386a4fcfe59390505",
    "param": "",
    "type": "Unauthorized"
  }
}

如果你看到的是 AuthenticationError,说明请求已经打到官方接口,问题在密钥,而不在 URL 或模型 ID。完整实录见本课工作目录中的 transcripts/。

做完后把环境变量改回真实 Key:

export ARK_API_KEY="YOUR_API_KEY"

常见坑

  • 把官方示例里的 doubao-seedance-2-5-260628 原样提交。那是旗舰 ID,本课要改成 doubao-seedance-2-5-flash-261115。
  • 把 Key 写进源码或把完整 Key 打进日志。只导出环境变量,打印时最多保留前缀。
  • 账户余额或资源包未达到官方开通门槛,就无法开通 Seedance 2.5 系列。
  • 在 Flash 上指定 1080p 或 4k。官方写明 Flash 只支持 480p、720p。
  • 以为创建接口会同步返回视频地址。官方写明这是异步接口,需要再查询任务。

小结

到这里,你已经认清了 Flash 的调用 ID,按官方步骤准备了 API Key,并用官方文生视频示例准备好了 SDK 和 curl 请求。成功成片采用官方文档示例,本环境未用真实密钥跑出成功视频。下一课会查询任务状态,阅读成功与失败返回,并取出成片地址。