抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • JS API 列表
  • 基础
  • TTML
  • 网络
  • 媒体
  • 地图
  • 文件
  • 数据缓存
  • 地理位置
  • 设备
  • 画布
  • 界面
  • 页面导航
  • 开放接口
  • 登录
  • 用户信息
  • 广告
  • 营销能力
  • 支付
  • 分享
  • 小程序跳转
  • 抖音视频能力
  • 收货地址
  • 设置
  • 授权
  • 评价能力
  • 数据分析
  • 视频拍摄器
  • 引导关注
  • 订阅消息
  • 电商插件能力(即将废弃)
  • 流量来源识别
  • 隐私信息授权
  • web化
  • 转发和挂载
  • 概述
  • 分享
  • 视频发布和挂载
  • UploadOption
  • UploadParam
  • 直播挂载
  • 视频拍摄器
  • tt.showShareMenu
  • tt.hideShareMenu
  • tt.navigateToVideoView
  • 侧边栏能力
  • 直播能力
  • AI/AR能力
  • 安全能力
  • 行业开放
  • 第三方平台
  • 其它
  • 生活服务(即将废弃)
  • UploadParam 是开发者在 Page.onUploadDouyinVideo 钩子中返回的值,该返回值会作为上传参数,最终传递给发布器(注:uploadParam 支持众多抖音视频配置,数据结构较为复杂,可参考下文结构示例与代码辅助理解。如无特殊需求也可以只返回 videoPath,不使用任何特殊能力)。开发者可以根据约定传入部分自定义数据,属性如下:
    属性
    类型
    默认值
    是否必填
    说明
    最低支持版本
    videoPath
    string
      基础库 3.2.0 开始,未填时,代表拉起拍摄器拍摄;
      设置了此属性,代表要发布的视频路径,只支持 ttfile 格式(可通过如 tt.chooseVideo 等 API 获取),暂不支持网络视频资源。
    2.65.0
    titleConfig
    TitleConfig
    视频的标题配置,详情参考TitleConfig 类型说明
    2.65.0
    stickersConfig
    StickersConfig
    视频的贴图配置,详情参考stickersConfig 类型说明
    2.65.0
    taskIds
    string[]
    拍抖音任务 id 列表,用户完成拍抖音后,会在success回调内返回当前用户的对应任务完成信息
    3.2.0
    extra
    Extra
    挂载锚点等额外信息,详情参考Extra 类型说明
    2.65.0
    success
    function
    发布成功的回调函数
    2.65.0
    fail
    function
    发布失败的回调函数
    2.65.0
    complete
    function
    发布成功或失败时都会执行的回调函数
    2.65.0

    TitleConfig 类型说明

    object 类型,属性如下:
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    title
    string
    ''
    发布视频的标题,字数限制为 60 个字
    2.65.0
    mentionMarkers
    MentionMarker[]
    []
    数据结构为 MentionMarker 组成的数组,往标题中某个位置插入提醒标记,表现为 @xxx,详情参考MentionMarker 类型说明
    2.65.0
    hashtagMarkers
    HashtagMarker[]
    []
    数据结构为 HashtagMarker 组成的数组,往标题中某个位置插入话题标记,表现为 #xxx,详情参考HashtagMarker 类型说明
    2.65.0

    MentionMarker 类型说明

    object 类型,属性如下:
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    start
    number
    0
    在 title 中插入标记的起始位置下标,有效区间为 [0, 标题长度],小于 0 时会被重置成 0、大于标题长度时会被重置成标题长度
    2.65.0
    openId
    string
    ''
    该 mentionMarker 提醒的人,表现为 @xxx
    2.65.0

    HashtagMarker 类型说明

    object 类型,属性如下:
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    start
    number
    0
    在 title 中插入标记的起始位置下标,有效区间为 [0, 标题长度],小于 0 时会被重置成 0、大于标题长度时会被重置成标题长度
    2.65.0
    hashtag
    string
    ''
    该 hashtagMarker 的话题,表现为 #xxx
    2.65.0

    stickersConfig 类型说明

    object 类型,属性如下:
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    text
    TextSticker[]
    []
    视频上的文字贴图,数据结构为 TextSticker 组成的数组,详情参考 TextSticker 类型说明
    2.65.0
    hashtag
    HashtagSticker[]
    []
    视频上的话题贴图,数据结构为 HashtagSticker 组成的数组,详情参考 HashtagSticker 类型说明
    2.65.0
    mention
    MentionSticker[]
    []
    视频上的提醒贴图,数据结构为 MentionSticker 组成的数组,详情参考 MentionSticker 类型说明
    2.65.0
    custom
    CustomSticker[]
    []
    视频上的自定义贴图, 数据结构为 CustomSticker 组成的数组,详情参考 CustomSticker 类型说明
    2.65.0

    TextSticker 类型说明

    object 类型,属性如下:
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    text
    string
    文字贴图的文本
    2.65.0
    color
    string
    '#ffffff'
    16 进制 hex 格式的颜色,如 #ffffff
    2.65.0
    fontSize
    number
    28
    贴图字体大小,单位为像素
    2.65.0
    scale
    number
    1
    贴图放大倍率,最小值是 0,精度为 2 位小数
    2.65.0
    x
    number
    0.5
    贴图中心点的横坐标位置,0 表示在屏幕最左边,1 表示在屏幕最右边,默认为 0.5 表示水平居中。精度为 2 位数,区间是 [0, 1],超出范围时会被重置成 0.5
    2.65.0
    y
    number
    0.5
    贴图中心点的纵坐标位置,0 表示在屏幕最上边,1 表示在屏幕最下边,默认为 0.5 表示垂直居中。精度为 2 位数,区间是 [0, 1],超出范围时会被重置成 0.5
    2.65.0

    HashtagSticker 类型说明

    object 类型,属性如下:
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    name
    string
    话题名称,话题不能带空格
    2.65.0
    x
    number
    0.5
    贴图中心点的横坐标位置,0 表示在屏幕最左边,1 表示在屏幕最右边,默认为 0.5 表示水平居中。精度为 2 位数,区间是 [0, 1],超出范围时会被重置成 0.5
    2.65.0
    y
    number
    0.5
    贴图中心点的纵坐标位置,0 表示在屏幕最上边,1 表示在屏幕最下边,默认为 0.5 表示垂直居中。精度为 2 位数,区间是 [0, 1],超出范围时会被重置成 0.5
    2.65.0

    MentionSticker 类型说明

    object 类型,属性如下:
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    openId
    string
    提醒的人
    2.65.0

    CustomSticker 类型说明

    object 类型,属性如下:
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    path
    string
    自定义贴图路径,只支持 ttfile 格式(可通过如 tt.chooseImage 等 API 获取),暂不支持网络图片资源
    2.65.0
    scale
    number
    1
    贴图放大倍率,最小值是 0,精度为 2 位小数
    2.65.0
    rotate
    number
    0
    贴图旋转角度,正数代表顺时针旋转,负数代表逆时针旋转(如 90 表示顺时针旋转 90 度)
    2.65.0
    x
    number
    0.5
    贴图中心点的横坐标位置,0 表示在屏幕最左边,1 表示在屏幕最右边,默认为 0.5 表示水平居中。精度为 2 位数,区间是 [0, 1],超出范围时会被重置成 0.5
    2.65.0
    y
    number
    0.5
    贴图中心点的纵坐标位置,0 表示在屏幕最上边,1 表示在屏幕最下边,默认为 0.5 表示垂直居中。精度为 2 位数,区间是 [0, 1],超出范围时会被重置成 0.5
    2.65.0

    Extra 类型说明

    object 类型,属性如下:
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    anchor
    Anchor
    锚点配置,详情参考Anchor 类型说明
    2.65.0
    createChallenge
    boolean
    false
    是否分享为挑战视频 ( 仅头条支持 )
    3.2.0

    Anchor 类型说明

    object 类型,属性如下:
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    anchorType
    "none" | "app"
    "none"
    挂载锚点的类型,"none" 表示不挂载,"app" 表示将小程序锚点挂载到发布的抖音视频上,暂不开放挂载其他场景的能力。挂载小程序需要申请挂载权限
    2.65.0
    title
    string
    小程序名称
    挂载锚点的文案,为空时展示小程序名称
    2.65.0
    path
    string
    小程序首页
    点击锚点时打开小程序的页面。是相对路径,相对于小程序根目录,如 page/about/about,默认是小程序首页
    2.65.0

    完整结构示例

    const uploadParamsDemo = { videoPath: "ttfile://xxx", titleConfig: { title: "视频标题", mentionMarkers: [ { start: 0, openId: "标题里要 @ 的人", }, ], hashtagMarkers: [ { start: 0, hashtag: "标题里要 # 的话题", }, ], }, stickersConfig: { text: [ { text: "这是文字贴图", color: "#ffffff", fontSize: 28, scale: 1, x: 0.5, y: 0.5, }, ], hashtag: [ { name: "这是话题贴图", x: 0.5, y: 0.5, }, ], mention: [ { openId: "这是 @ 贴图", }, ], custom: [ { path: "ttfile://xxx", scale: 1, rotate: 0, x: 0.5, y: 0.5, }, ], }, extra: { anchor: { anchorType: "app", title: "挂载锚点的标题", path: "page/about/about", }, }, success: function (res) { console.log("success: ", res); }, fail: function (res) { console.log("fail: ", res); }, complete: function (res) { console.log("complete: ", res); }, };

    发布成功回调

    如果返回的 UploadParam 中有 success 回调函数,那么在发布视频成功后会触发该成功回调。回调函数携带参数,为 object 类型,属性如下:
    属性名
    类型
    说明
    最低支持版本
    videoId
    string
    如果发布成功且成功挂载锚点,则返回 videoId,此 id 与发布的抖音视频存在一一对应的映射关系,能通过 OpenAPI 换取抖音视频,也能通过 button(open-type=navigateToVideoView) 组件跳转到该视频页面
    2.65.0
    taskResult
    TaskResult[]
    当前用户的拍抖音任务结果,当 UploadParam 有传入 taskIds 才会返回
    3.2.0
    type
    string
    目前支持video 和 image ,代表当前展示的是视频还是图文,仅在拍抖音场景下返回
    3.2.0
    errMsg
    string
    "uploadDouyinVideo:ok"
    2.65.0

    TaskResult

    属性名
    类型
    说明
    最低支持版本
    taskId
    string
    任务id
    3.2.0
    completed
    boolean
    当前用户在该任务的状态,true代表已全部完成,false代表未完成
    3.2.0
    successCount
    number
    当前用户在该任务的进度
    3.2.0
    increaseCount
    number
    本次拍抖音带来的任务完成人数的进度更新
    3.2.0
    isValid
    boolean
    任务是否还在有效期
    3.2.0
    errNo
    number
    错误码
    3.2.0
    errMsg
    string
    错误信息
    3.2.0

    发布失败回调

    如果返回的 UploadParam 中有 fail 回调函数,那么在发布视频失败后会触发该失败回调。回调函数携带参数,为 object 类型,属性如下:
    属性名
    类型
    说明
    最低支持版本
    errNo
    number
    错误码
    2.65.0
    errMsg
    string
    "uploadDouyinVideo:fail" + 详细错误信息
    2.65.0

    发布完成回调

    如果返回的 UploadParam 中有 complete 回调函数,那么无论发布视频成功与否,都会触发该回调。回调函数携带的参数根据发布情况略有不同:
      1.当发布成功时,与 “发布成功回调” 里的回调参数一致
      2.当发布失败时,与 “发布失败回调” 里的回调参数一致

    代码示例

    <!-- index.ttml --> <button open-type="uploadDouyinVideo" id="1" data-hello="world"> uploadDouyinVideo </button>
    // index.js Page({ data: {}, // onUploadDouyinVideo 和 onLoad 等其他钩子同级 async onUploadDouyinVideo(uploadOptions) { // 通过 UploadOption 可以拿到 button target 上的一些信息 // 如这里的 demo 可以拿到 id: "1",hello: "world" console.log("onUploadDouyinVideoOptions: ", uploadOptions); // 可以利用异步能力配合其他 API 获取必要的字段信息 const videoPath = await this.chooseVideo(); console.log("videoPath:", videoPath); // 返回值(文档中称之为 UploadParam)将被当作发布参数传入视频发布器,发布视频 return { videoPath, stickersConfig: { text: [ { text: "这是文字贴图", color: "#ffffff", fontSize: 28, scale: 1, x: 0.5, y: 0.5, }, ], }, success: function (callback) { // 只有当发布成功且挂载成功时,success callback 才会有 videoId console.log("success: ", callback); }, fail: function (callback) { console.log("fail: ", callback); }, complete: function (callback) { console.log("complete: ", callback); }, }; }, chooseVideo() { return new Promise((resolve) => { tt.chooseVideo({ sourceType: ["album", "camera"], compressed: true, success: (res) => { resolve(res.tempFilePath); }, fail: (err) => { let errType = err.errMsg.includes("chooseVideo:fail cancel") ? "取消选择" : "选择失败"; tt.showModal({ title: errType, content: err.errMsg, showCancel: false, }); resolve(""); }, }); }); }, });

    Bug & Tip

      Tip:titleConfig.mentionMarkers + stickersConfig.mention 总数不能超过 5 个,超过 5 个将会截取前 5 个 mention;
      Tip:titleConfig.hashtagMarkers + stickersConfig.hashtag 总数不能超过 5 个,超过 5 个将会截取前 5 个 hashtag。