抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • OpenAPI 简介
  • 通用参数
  • 小程序 OpenAPI SDK 总览
  • 签名算法
  • 基础能力
  • 联合授权
  • 视频能力
  • 线索组件
  • 接口调用凭证
  • 登录
  • Web 化接入
  • 隐私协议
  • 流量主
  • 小程序码与小程序链接
  • 用户信息
  • 抖音号绑定
  • 小程序推广计划
  • 短视频任务
  • 创建任务-v2
  • 重新提交任务基础信息-v2
  • 更新任务状态-v2
  • 查询小程序任务台任务 ID-v2
  • 查询任务详情-v2
  • 查询任务台任务投稿视频数据(明细)-v2
  • 查询任务台任务投稿视频数据-v2
  • 更新专属任务达人
  • 查询推广视频数据下载链接
  • 查询视频任务相关实时汇总数据
  • 直播间任务
  • 内容安全
  • 任务能力
  • 分享
  • 客服
  • 小程序券
  • 触达与营销
  • 支付
  • 运营
  • 生活服务
  • 垂直行业
  • 其它
  • 接入流程简介

    使用文档所述 OpenAPI 前需要在开发者平台上开通任务台相关功能。

    重要字段说明

    任务标签字段说明

    任务中的标签字段请选择两个维度的标签:

    1. 形态:共 12 类

    图片互动类/声音互动类/游戏化/图像处理类/生成转换类/计算器类/在线应用类/信息查询类/资源获取/测试类/答题类/其他
    形态玩法(旧)
    形态玩法(新)
    说明
    举例
    备注
    图片互动类
    娱乐测试
    最终目的是获取测试结果,例如影音互动测试,答题测试等
    AI颜值评分、AI造型屋、录绕口令、录歌、影视测试、王者荣耀答题闯关
    声音互动类
    测试类
    答题类
    游戏化
    游戏
    偏游戏互动类型
    测手速、华容道、模拟器
    图像处理类
    AI生成
    图片的在线设计&编辑制作;文件、文案、视频的生成或转换
    漫画脸制作、表情包制作、证件照生成、名片设计、logo设计、文件格式转换、翻译、足迹生成、对联生成
    生成转换类
    计算器类
    实用工具
    实用、娱乐小工具;例如日程表、智能检测、记事本等
    BMI计算、保质期计算、倒计时、记事本、日程表、智能检测、投票
    在线应用类
    信息查询类
    (删除)
    获取信息或新闻
    电影档期、娱乐资讯、地址查询
    资源获取
    内容消费
    电影档期、娱乐资讯、地址查询等
    表情包、小说、影视、相声
    注意版权问题
    (新增)
    教育培训
    泛知识类型
    Excel基础入门
    其他
    其他
    其他以上未覆盖类型

    2. 内容:共 18 类

    心理/游戏/影视综/二次元/美食/萌宠/亲子/旅游/时尚/颜值/随拍/音乐/舞蹈/体育/健身/泛知识/居家休闲/科技/财经/汽车/其他。
    内容名称(旧)
    内容名称(新)
    说明
    小说
    小说
    长短篇小说资讯、阅读
    漫画
    漫画
    漫画相关资讯、阅读
    心理
    情感心理
    情感、成长、职场技能
    游戏
    游戏
    角色扮演、竞技游戏、动作游戏、射击游戏、游戏其他、解说游戏
    影视综
    影视综
    影视剪辑、影视解说
    普通综艺、脱口秀、其他综艺
    二次元
    二次元
    二次元衍生、二次元内容、二次元资讯、二次元其他
    美食
    美食
    美食教程、评测、吃播、山野村食、美食知识、美食展示
    萌宠
    萌宠
    宠物猫、狗、其他动物、宠物资讯
    亲子
    亲子
    母婴、儿童、亲子日常
    旅游
    旅游
    旅行vlog、旅行攻略、旅行摄影、酒店/民宿测评、导游
    时尚
    颜值时尚
    帅哥、美女人物随拍、录屏、生活记录;彩妆、护肤、穿搭、资讯
    颜值随拍
    音乐
    音乐
    音乐演唱、西洋乐器、民族乐器、音乐知识
    舞蹈
    舞蹈
    专业舞蹈、手势舞蹈、民族舞、广场舞
    体育
    体育
    竞技体育、水/雪上运动、极限运动、球类项目、体育运动文化
    健身
    健身
    专业健身、生活健身、健身知识
    绘画
    绘画
    绘画知识、课程、画展相关信息等等
    居家休闲
    居家休闲
    装修设计、生活窍门、家具家电、园艺花艺、手工diy
    魔术、多米诺骨牌类、开箱、玩具、棋牌
    科技财经
    科技财经
    手机、电脑、电器、科技周边、行业资讯
    投资理财、金融产品、财经新闻、财经知识、房产、实体经济
    汽车
    汽车
    看车、选车、买车、用车、学车、汽车周边
    其他
    其他
    ①片场演绎、明星资讯、明星访谈
    ②剧情、演绎
    ③医疗机构、医疗用品、健康
    ④户外打野、赶海、农村生活、农业技术、农业资讯、国外泛三农
    ⑤时政新闻、军事、军事

    接口说明

    该接口用于小程序任务台创建任务。

    使用限制

    无。

    基本信息

    名称描述
    HTTP URL
    https://open.douyin.com/api/match/v2/taskbox/add_task/
    HTTP Method
    POST
    Scope
    match_taskbox.default.plan_permission
    权限要求
    服务商代调用场景下,需商家授予小程序推广计划-任务管理权限。

    请求参数

    请求头
    access-token必填String
    当非服务商时,调用https://open.douyin.com/oauth/client_token/生成的token
    当服务商时,调用https://open.douyin.com/api/tpapp/v2/auth/get_auth_token/生成的token
    content-type必填String
    示例:application/json
    固定值"application/json"
    Body展开全部子属性
    task_desc必填String

    产品介绍30-100字;任务要求<200字,条数不限,仅支持纯文本输入,不可包含html标签。

    举例

    1. 产品介绍:该产品是一个XX类型的小程序,可以XXX。
    2. 达人视频内需添加与小程序页面相关的内容,杜绝生硬植入。
    3. 达人视频内容表现积极向上,禁止出现恶俗、违背公序良俗类内容或品牌负面
    4. 视频原创,拒绝拼接,搬运,虚假骗互动内容。


    注意:

    1.任务台的方案 只能计算小程序内收入,如果是iOS虚拟支付的,走了小店的那部分无法计费,需要开发者在产品说明中明确写出来,如:「请注意:该小程序内iOS端的订单收入不计入分成收入,仅计算安卓端订单收入。」

    task_end_time必填Int64

    任务结束时间,秒级时间戳。开始时间与结束时间相差要求大于30天

    task_icon必填String
    • 尺寸为512*512的当前任务图标,大小不超过200KB,支持PNG,JPG格式
    • 不允许出现留边的情况,图片必须铺满
    task_name必填String
    • 任务名称
    • 长度:限制在17个字以内
    • 不得包含特殊字符,除[、,、。、!、?、“、”、《、》「、」、]以外
    • 不得包含敏感字符,例如“全网第一”
    • 任务名称请勿包含公司名称!
    • 任务标题相同,任务时间重叠。即为重复上传任务,不支持上传
    • 同一个小程序,上传相似标题、相同页面地址的任务,会审核不通过
    task_settle_type必填Int32
    • 结算方式,类型包含:1-广告分成、2-支付分成(基础)、3-支付分成(绑定)、7-广告分成+支付分成(基础)、8-广告分成+支付分成(绑定)
    • 支付CPS必须接入小程序担保交易,且需另外配置最长可退款时间和分佣比例
    task_start_time必填Int64

    任务开始时间,秒级时间戳

    task_tags必填Array<String>
    • 任务标签
    • 开发者勾选两个维度的标签:形态+内容,成为数组的两个元素
    • 见本文档开头任务标签字段说明
    • 必须按表里的填,不要自己命名!
    anchor_titleString
    • 上传的锚点标题,最多14个字。
    • 任务页面类型为达人自选页面时无需填写。
    douyin_idsArray<String>

    指定推广达人列表。可输入达人的抖音号,只支持输入已入驻小程序推广计划的达人。若为空,则创建普通任务,即所有已入驻小程序推广计划的达人都可以投稿;若不为空,则创建专属任务,只有输入的达人可投稿

    mix_payment_allocate_ratioMap
    示例:1: "2500" 3: "2500"
    • 混合分成达人分成比例(包含服务费)。
    • 当结算方式是 广告+支付分成(基础)或 广告+支付分成(绑定)(即task_settle_type为7或8)的时候必填,表示每种结算方式的分成比例。
    • 比如结算方式是:广告+支付分成(基础),这个值需要填写广告分成的比例,和支付分成(基础)的分成比例。
    • 百分号整数类型(仅支持整数),4500代表45%
    • 与talent_mix_payment_allocate_ratio字段互斥,如果都传递,以talent_mix_payment_allocate_ratio优先级更高。
    展开子属性
    page_typeEnum
    示例:1

    任务页面类型:0或不填-开发者指定任务的小程序页面地址,1-达人自选页面。

    展开子属性
    payment_allocate_ratioInt32
    示例:4500
    • 达人分成比例(含服务费)
    • 百分号整数类型(仅支持整数),4500代表45%,广告分成范围[1000,10000],支付分成比例范围受支付担保方式、小程序行业影响有所区别,请先按照预期的分成比例入参,若报错则留意接口返回的范围要求,建议值[5200,7400]
    • 当结算方式是支付分成的时候必填(即task_settle_type为2和3);
    • 当结算方式是广告分成的时候选填(即task_settle_type为1),不填则为默认的70%;
    • 当结算方式是 广告+支付分成(基础)或 广告+支付分成(绑定)(即task_settle_type为7或8)的时候不需要填写,需要填写mix_payment_allocate_ratio或者talent_mix_payment_allocate_ratio。
    • 与talent_payment_allocate_ratio字段互斥,如果都传递,以talent_payment_allocate_ratio优先级更高。
    refer_gidsArray<Int64>

    示例视频的gid数组,当传了 refer_videos 字段时,会自动使用 refer_videos 的视频作为示例视频,本字段无效

    refer_ma_capturesArray<String>

    小程序落地页截图。单个图片大小上限为2M,可上传0-3张,尺寸要求为312*444

    refer_videosArray<String>
    • 示例视频
    • 0-5个,校验是可以打开的视频,如被删除或其他原因则不展示
    • 会审核视频内容、视频锚点与任务的相关性,低质/无意义/录屏/不含小程序锚点会审核不通过
    • 从移动端复制视频链接,正确格式为:https//v.Douyin.com /xxxxx
    • 视频需包含任务对应的小程序锚点!
    start_pageString
    示例:page/detail/detail?id=1
    • 小程序页面地址,包含path和query,path不得以 "/" 开头。
    • 任务页面类型为达人自选页面时无需填写。
    talent_mix_payment_allocate_ratioMap
    • 混合分成达人分成比例(不包含服务费),纯粹给达人的分成比例
    • 百分号整数类型(仅支持整数),4500代表45%
    • 当结算方式是 广告+支付分成(基础)或 广告+支付分成(绑定)(即task_settle_type为7或8)的时候必填,但与mix_payment_allocate_ratio字段互斥,如果都传递,则以该字段优先级最高。
    • 比如结算方式是:广告+支付分成(基础),这个值需要填写广告分成的比例,和支付分成(基础)的分成比例。
    展开子属性
    talent_payment_allocate_ratioInt32
    • 达人结算分成比例(不包含服务费), 纯粹给达人的分成比例。
    • 百分号整数类型(仅支持整数),4500代表45%,广告分成范围[1000,9500],支付分成比例范围受支付担保方式、小程序行业影响有所区别,请先按照预期的分成比例入参,若报错则留意接口返回的范围要求,建议值[5000,7000]。
    • 当结算方式是支付分成的时候必填(即task_settle_type为2和3);
    • 当结算方式是广告分成的时候选填(即task_settle_type为1),不填则为默认的70%;
    • 与payment_allocate_ratio字段互斥,如果都传,以这个字段优先级更高。
    • 当结算方式是 广告+支付分成(基础)或 广告+支付分成(绑定)(即task_settle_type为7或8)的时候不需要填写,需要填写mix_payment_allocate_ratio或者talent_mix_payment_allocate_ratio。
    task_refund_periodInt32
    • 订单最长退款周期,当结算方式是支付分成的时候必填(即task_settle_type为2或3或7或8),广告分成任务不用填
    • 不超过10天,不少于0天
    请求示例
    # 创建普通任务 curl --location --request POST 'https://open.douyin.com/api/match/v2/taskbox/add_task/' \ --header 'Content-Type: application/json; charset=utf-8' \ --data-raw '{ "task_name":"测试12333", "task_settle_type":1, "start_page":"page/index=1", "anchor_title":"测试锚点标题", "task_icon":"https://gimg2.baidu.com/image_search/src=http%3A%2F%2Fpic.soutu123.cn%2Felement_origin_min_pic%2F01%2F35%2F26%2F55573bdad4cb2f4.jpg%21%2Ffw%2F700%2Fquality%2F90%2Funsharp%2Ftrue%2Fcompress%2Ftrue&refer=http%3A%2F%2Fpic.soutu123.cn&app=2002&size=f9999,10000&q=a80&n=0&g=0n&fmt=jpeg?sec=1621156196&t=848be9cae3f5bfb86a12d5021cbf9c1f", "task_start_time":1618285226, "task_end_time":1620963626, "task_desc":"1. sss <br>2.sss2", "refer_videos":["http://douyin.com/Z0JRdbe/","http://douyin.com/beeagag/"], "task_tags":["测试类","心理"], "refer_ma_captures":["https://static.runoob.com/images/demo/demo1.jpg","https://static.runoob.com/images/demo/demo2.jpg"] }' # 创建专属任务 curl --location --request POST 'https://open.douyin.com/api/match/v2/taskbox/add_task/' \ --header 'Content-Type: application/json; charset=utf-8' \ --data-raw '{ "task_name":"测试12333", "task_settle_type":1, "start_page":"page/index=1", "anchor_title":"测试锚点标题", "task_icon":"https://gimg2.baidu.com/image_search/src=http%3A%2F%2Fpic.soutu123.cn%2Felement_origin_min_pic%2F01%2F35%2F26%2F55573bdad4cb2f4.jpg%21%2Ffw%2F700%2Fquality%2F90%2Funsharp%2Ftrue%2Fcompress%2Ftrue&refer=http%3A%2F%2Fpic.soutu123.cn&app=2002&size=f9999,10000&q=a80&n=0&g=0n&fmt=jpeg?sec=1621156196&t=848be9cae3f5bfb86a12d5021cbf9c1f", "task_start_time":1618285226, "task_end_time":1620963626, "task_desc":"1. sss <br>2.sss2", "refer_videos":["http://douyin.com/Z0JRdbe/","http://douyin.com/beeagag/"], "task_tags":["测试类","心理"], "refer_ma_captures":["https://static.runoob.com/images/demo/demo1.jpg","https://static.runoob.com/images/demo/demo2.jpg"], "douyin_ids": ["lw123456","lv789"] }'

    响应参数

    Body展开全部子属性
    err_msg必填String
    示例:success

    错误信息

    err_no必填Int32
    示例:0

    错误码,0 是成功,其它为异常

    log_id必填String
    示例:202008121419360101980821035705926A

    标识请求的唯一id,在接口异常时用于问题排查

    dataStruct
    展开子属性
    响应示例
    正常响应示例异常响应示例
    { "err_no": 0, "err_msg": "success", "log_id": "202008121419360101980821035705926A", "data": { "task_id": 720992698146361 } }
    切换单列布局

    错误码

    HTTP 状态码错误码错误码描述排查建议
    2000
    请求操作成功
    2005401
    没有支付分成比例或者最大退款周期
    2005402
    参考视频截图数量不合法
    2005403
    小程序落地页参考视频截图数量不合法
    2005404
    任务描述长度不合法
    2005405
    任务开始与结束时间必须大于 30 天
    2005406
    小程序落地页截图数量不合法
    2005408
    锚点标题长度不合法
    2005409
    任务标签长度不合法
    2005410
    任务名称长度不合法
    2005411
    传入的 appid 不是小程序
    2005412
    最大退款周期不合法
    2005413
    支付分成比例不合法
    2005414
    传入图片的宽高不合法
    2005415
    图片大小不合法
    2005416
    无效的图片链接
    2005417
    任务 id 传入的数量太多
    2005418
    找不到对应的小程序
    2005419
    找不到 gid 列表
    2005420
    gid 找不到对应的视频
    2005421
    gid 数量过多
    2005422
    超时相关的问题
    2005423
    没有支付分成比例或者最大退款周期
    2005424
    找不到相应的结算模式
    2005425
    非法视频,请检查视频
    2005426
    重复任务
    2005427
    该小程序已经达到当天上传任务的次数限制
    2005428
    图片解析错误
    2005429
    当前小程序无配置,请联系相关人员添加任务相关配置
    2005430
    当前小程序无短视频挂载能力
    2005431
    当日灰度名额已满
    2005432
    未满足达到发布此类任务门槛
    2005433
    小程序未开启任务台
    2005434
    小程序已加任务台黑名单
    2005435
    小程序已下架
    2005436
    小程序已经开启任务台
    2005437
    小程序类别限制
    2005438
    小程序未上线
    2005481
    不得包含特殊字符
    2005482
    不得包含敏感字符号“${敏感字符}”
    2005483
    任务标签不合法
    2005515
    调用者无权限
    请服务商前往「服务商平台-能力-代商家管理能力-小程序推广计划」完成协议签署
    2005516
    调用者无权限
    请服务商前往「服务商平台-设置-权限设置」申请该小程序的「小程序推广计划-任务管理」权限
    2005517
    该小程序暂未完成撮合平台协议的签署
    请开发者前往「开发者平台-运营-小程序推广计划」完成协议签署
    2005518
    该小程序暂无达人推广挂载能力
    请服务商前往「服务商平台-能力-代商家管理能力-短视频达人推广挂载」开通
    2005600
    该小程序暂无达人推广挂载能力
    请服务商前往「服务商平台-能力-代商家管理能力-短视频达人推广挂载」开通
    20028001018
    应用未获得该能力
    请服务商前往「服务商平台-设置-权限设置」申请该小程序的「小程序推广计划-任务管理」权限
    2004001015
    1. Request Paramter Error 2. html标签不可用,任务介绍仅支持纯文本输入
    1.请检查参数是否正确 2.请检查task_desc是否包含html标签
    2004010003

    暂不支持推广该页面地址

    1. 自查资源等级
    2. 资源格式是否正确
    3. 资源是否上线
    2005613

    请先开通“直播达人推广挂载”权限

    注意事项

      发布的参考视频一定要挂任务对应的小程序锚点
      落地页的启动路径不得以 "/" 开头
      任务介绍task_desc 不可包含html标签