> For the complete documentation index, see [llms.txt](https://polyv.gitbook.io/document/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://polyv.gitbook.io/document/docs/live/api/channel/player/update_head.md).

# 设置播放器片头广告

### 接口描述

```
1、接口用于设置某频道播放器的片头广告
2、接口URL中的{channelId}为 频道ID
3、接口支持https
```

### 接口URL

```
http://api.polyv.net/live/v2/channelAdvert/{channelId}/updateHead
```

### 请求方式

```
POST
```

### 支持格式

```
JSON
```

### 请求数限制

```
TRUE
```

### 请求参数

| 参数名                | 必选 | 类型     | 说明                                |
| ------------------ | -- | ------ | --------------------------------- |
| appId              | 是  | string | 从API设置中获取，在直播系统登记的appId           |
| timestamp          | 是  | string | 当前13位毫秒级时间戳，3分钟内有效                |
| sign               | 是  | string | 签名，32位大写MD5值                      |
| enabled            | 否  | string | Y-开启，N-关闭；设置开关时，其余设置参数无效          |
| headAdvertType     | 否  | string | 广告类型,NONE-无广告，IMAGE-图片广告，FLV-视频广告 |
| headAdvertMediaUrl | 否  | string | 广告地址                              |
| headAdvertHref     | 否  | string | 广告跳转地址                            |
| headAdvertDuration | 否  | int    | 广告时长                              |
| headAdvertWidth    | 否  | int    | 广告宽度                              |
| headAdvertHeight   | 否  | int    | 广告高度                              |
| ### 响应成功JSON示例：    |    |        |                                   |

```json
{
    "code": 200,
    "status": "success",
    "message": "",
    "data": true
}
```

### 响应失败JSON示例：

未输入appId

```json
{
    "code": 400,
    "status": "error",
    "message": "appId is required.",
    "data": ""
}
```

appId不正确

```json
{
    "code": 400,
    "status": "error",
    "message": "application not found.",
    "data": ""
}
```

时间戳错误

```json
{
    "code": 400,
    "status": "error",
    "message": "invalid timestamp.",
    "data": ""
}
```

签名错误

```json
{
    "code": 403,
    "status": "error",
    "message": "invalid signature.",
    "data": ""
}
```

频道不存在

```json
{
    "code": 400,
    "status": "error",
    "message": "channel not found.",
    "data": ""
}
```

频道类型错误

```json
{
    "code": 400,
    "status": "error",
    "message": "invalid advert type",
    "data": ""
}
```

开关参数错误

```json
{
    "code": 400,
    "status": "error",
    "message": "invalid enabled value",
    "data": ""
}
```

非法请求

```json
{
    "code": 403, 
    "status": "error", 
    "message": "operation forbidden.", 
    "data": ""
}
```

### 字段说明

| 参数名     | 说明                            |
| ------- | ----------------------------- |
| code    | 请求结果代码，成功为200 错误为400，签名错误为403 |
| status  | 请求结果，成功时为"success"错误时为"error" |
| message | 错误信息，请求成功时为空串，错误时错误信息         |
| data    | 请求成功为true，错误为空串               |

### php请求示例

```php
<?php
//引用config.php
include 'config.php';

//接口需要的参数（非sign）赋值
$channelId="123713";

$headAdvertType = "none";
$headAdvertMediaUrl = "http://www.headAdvertMediaUrl.com";
$headAdvertHref = "http://www.headAdvertHref.com";
$headAdvertDuration = 50;
$headAdvertWidth = 100;
$headAdvertHeight = 200;

$params = array(
    'appId' => $appId,
    'timestamp' => $timestamp,
    'headAdvertType' => $headAdvertType,
    'headAdvertMediaUrl' => $headAdvertMediaUrl,
    'headAdvertHref' => $headAdvertHref,
    'headAdvertDuration' => $headAdvertDuration,
    'headAdvertWidth' => $headAdvertWidth,
    'headAdvertHeight' => $headAdvertHeight
  );

//生成sign
$sign = getSign($params); //详细查看config.php文件的getSign方法


$url="http://api.polyv.net/live/v2/channelAdvert/".$channelId."/updateHead";

function post($url, $post_data = '', $timeout = 5){
   $ch = curl_init();
   curl_setopt ($ch, CURLOPT_URL, $url);
   curl_setopt ($ch, CURLOPT_POST, 1);
   if($post_data != ''){
      curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
   }

   curl_setopt ($ch, CURLOPT_RETURNTRANSFER, 1);
   curl_setopt ($ch, CURLOPT_CONNECTTIMEOUT, $timeout);
   curl_setopt($ch, CURLOPT_HEADER, false);
   $file_contents = curl_exec($ch);
   curl_close($ch);
   return $file_contents;
}

$params["sign"] = $sign;
echo post($url, $params);
?>
```

### 签名规则(config.php文件代码查看)

[签名生成规则](https://git.polyv.net/help-center/document-center/-/blob/master/live/api/buildSign/README.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://polyv.gitbook.io/document/docs/live/api/channel/player/update_head.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.